Testing the SDK

Relevant source files

The following files were used as context for generating this wiki page:

• tests/AGENTS.md
• dev/constitution.md
• tasks.py
• AGENTS.md
• pyproject.toml
• specs/001-marketplace-api-update/tasks.md
• specs/001-end-user-cli/tasks.md

Testing the Infrahub Python SDK ensures the stability and correctness of the foundational library used by infrahubctl, Ansible collections, and external applications. The project follows a test-first development philosophy where every feature and bug fix must ship with corresponding tests. These tests validate the dual async/sync API parity, ensuring that both InfrahubClient and InfrahubClientSync behave identically across all public features.

The testing strategy divides into unit tests for fast, isolated logic verification and integration tests for validating behavior against real Infrahub server environments. The project utilizes pytest as the primary testing framework, supported by specialized tools like pytest-httpx for API mocking and testcontainers for integration environments.

Sources: dev/constitution.md:12-18, dev/constitution.md:65-72, AGENTS.md:15-18

Test-First Development Principles

The SDK mandates a "Test-First" approach to development. A bug fix must include a reproduction test that fails before the fix and passes after. All new public surfaces require testing for both the asynchronous and synchronous paths.

Core Testing Requirements

• Parity Validation: Tests in tests/unit/sdk/test_client.py assert surface parity between the async and sync clients using test_validate_method_signature and test_method_count.
• Concrete Assertions: Tests must assert specific expected values. Assertions that only check for "truthiness" or non-null values are insufficient.
• Speed and Isolation: Unit tests must remain fast and free of external dependencies by using mocks.
• Realism: Behavior requiring a real server must use integration tests via testcontainers.

Sources: dev/constitution.md:16-19, dev/constitution.md:65-72

Testing Architecture and Flow

The testing workflow is integrated into the project's development lifecycle via invoke tasks and CI gates.

This diagram shows the sequence of quality gates a developer must pass before submitting a change, moving from local code formatting to full integration testing and documentation validation.

Sources: tasks.py:195-260, AGENTS.md:27-36

Unit Testing

Unit tests focus on the internal logic of the SDK, such as argument parsing, local input validation, and data transformation. They are located in tests/unit/.

Specialized Unit Test Tools

Tool	Purpose	Source
pytest-httpx	Mocks HTTP responses for marketplace and client probes	specs/001-marketplace-api-update/tasks.md:11-13
typer.testing	Validates CLI command exit codes and output	specs/001-marketplace-api-update/tasks.md:37-40
unittest.mock	Mocks the InfrahubClient for CLI command tests	specs/001-end-user-cli/tasks.md:155-158

Command Testing Patterns

For CLI commands, the SDK uses the following pattern to ensure reliable execution:

1. Mocking: Mock the backend API response using pytest-httpx.
2. Execution: Invoke the command through the Typer runner.
3. Assertions: Verify the exit code (e.g., 0 for success, 1 for input errors, 2 for network errors) and inspect the console output for specific strings.

Sources: specs/001-marketplace-api-update/tasks.md:37-45, specs/001-end-user-cli/tasks.md:65-70

Integration Testing

Integration tests validate the end-to-end interaction between the SDK and an Infrahub server. These tests are located in tests/integration/.

Integration Flow

Integration testing typically involves the full CRUD (Create, Read, Update, Delete) lifecycle to ensure data persistence and API compatibility.

The diagram represents the standard sequence for an integration test verifying the full lifecycle of an infrastructure object.

Sources: specs/001-end-user-cli/tasks.md:86-90, dev/constitution.md:69-72

Testing Infrastructure and Environment

The testing environment is managed using uv and invoke. Dependencies are grouped in pyproject.toml to ensure consistent test runners.

Test Configuration (pyproject.toml)

Setting	Value	Description
asyncio_mode	auto	Automatically handles async test discovery
testpaths	["tests"]	Defines the root directory for tests
addopts	-vs --strict-markers	Standard flags for verbose output and coverage

Sources: pyproject.toml:98-106

Essential Commands

You must run these commands to maintain code quality:

• uv run pytest tests/unit/: Executes isolated logic tests.
• uv run pytest tests/integration/: Executes tests against a real server.
• uv run invoke lint-code: Runs ruff, ty, and mypy to verify type safety and style.
• uv run invoke docs-validate: Ensures generated documentation is in sync with code changes.

Sources: AGENTS.md:27-36, tasks.py:255-275

Conclusion

Testing in the Infrahub Python SDK is a mandatory component of the development workflow, governed by constitutional principles of parity and accuracy. By combining strict unit testing with comprehensive integration suites, the project maintains a stable contract for downstream consumers while enabling rapid iteration through automated quality gates.