Testing Framework
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub MCP Testing Framework provides a dual-layered approach to ensure the reliability of the Model Context Protocol (MCP) server. It combines a fast, Docker-free unit testing suite with a comprehensive integration testing tier that utilizes ephemeral Infrahub instances provisioned via infrahub-testcontainers. The framework enforces strict separation between these layers to maintain developer productivity while ensuring high-fidelity validation against real infrastructure backends.
Sources: specs/001-infrahub-testcontainers/plan.md, dev/constitution.md:65-79
Testing Architecture and Tiers
The framework categorizes tests into two primary tiers: Unit and Integration. This separation ensures that basic logic validation remains instantaneous, while complex interactions with Infrahub are verified in a realistic environment.
Unit Testing Tier
Unit tests live in tests/unit/ and execute without Docker or network dependencies. These tests focus on internal module logic, such as configuration validation, authentication flow (OIDC/token passthrough), and middleware behavior using mocks for the Infrahub SDK.
Integration Testing Tier
Integration tests live in tests/integration/ and require a Docker engine. They provision an ephemeral Infrahub stack for the duration of the test session. These tests drive the server via the in-process FastMCP Client to exercise the actual MCP-to-Infrahub contract, including schema resources, branch listings, and node operations.
The diagram above shows the selection logic between fast unit tests and container-based integration tests.
Sources: specs/001-infrahub-testcontainers/spec.md:58-69, specs/001-infrahub-testcontainers/plan.md
Integration Test Lifecycle
Integration tests follow a specific lifecycle managed by pytest fixtures to ensure isolation and performance.
- Session Startup: One Infrahub container stack is provisioned for the entire test session to avoid the 60–120s overhead of restarting containers for every test.
- Seeding: A minimal schema and baseline nodes are loaded into the
mainbranch. - Test Isolation: For every individual test, the framework creates a fresh Infrahub branch off
main. - Execution: The test interacts with the MCP server, which performs mutations only on the per-test branch.
- Teardown: The framework deletes the per-test branch after completion and destroys the Docker stack at the end of the session.
This sequence ensures that every integration test runs against a deterministic starting state.
Sources: specs/001-infrahub-testcontainers/research.md:D1, D9, specs/001-infrahub-testcontainers/tasks.md:T006-T010
Key Components and Tools
| Component | Description | Source File |
|---|---|---|
infrahub-testcontainers | Orchestrates the Docker-based Infrahub stack (Neo4j, Redis, Server). | plan.md |
FastMCP Client | An in-process client used to drive the MCP server during integration tests. | research.md:D2 |
integration Marker | A pytest marker used to opt-in to container-based tests. | spec.md:20-22 |
schema_minimal.yml | Minimal seed schema used to exercise MCP surface area. | tasks.md:T004 |
test_version_compat.py | Dedicated test to detect drift between SDK and Infrahub server versions. | research.md:D11 |
Sources: specs/001-infrahub-testcontainers/tasks.md, specs/001-infrahub-testcontainers/research.md
Quality Gates and Standards
The framework enforces several "Constitution" principles to maintain code quality:
- Branch-Safe by Default: Write operations MUST be isolated to session branches; the default branch is never modified during tests.
- Protocol Compliance: All tests MUST verify that tools, resources, and prompts conform to the open MCP standard.
- Fail-Fast: The suite detects missing prerequisites (like Docker) and fails immediately with actionable messages.
- Version Pinning: The Infrahub container image is pinned to specific versions to ensure reproducible results across CI and local environments.
Sources: dev/constitution.md:29-39, 65-79, specs/001-infrahub-testcontainers/spec.md:FR-007, FR-008
Test Execution Commands
The framework is primarily driven via uv and pytest.
# Run the full suite (default excludes integration)
uv run pytest
# Run only unit tests
uv run pytest tests/unit
# Run integration tests (requires Docker)
uv run pytest tests/integration -m integration
# Run integration tests and keep containers alive for debugging
INFRAHUB_TESTCONTAINERS_KEEP=1 uv run pytest tests/integration -m integration
Sources: GPT.md, specs/001-infrahub-testcontainers/research.md:D8, specs/001-infrahub-testcontainers/plan.md
The Infrahub MCP Testing Framework ensures that developers can move quickly with unit tests while maintaining absolute confidence in the system's ability to interact correctly with real production-grade infrastructure through its automated integration tier.