Integration Tests & Testcontainers

Relevant source files

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

• dev/guides/running-integration-tests.md
• tests/integration/conftest.py
• dev/guidelines/testing.md
• pyproject.toml
• AGENTS.md
• tests/integration/test_file_object.py

Integration tests verify the nornir-infrahub plugin against a live Infrahub stack. These tests use infrahub-testcontainers to manage ephemeral Docker containers, providing a real environment for validating inventory loading, schema mappings, and task plugin execution. Unlike unit tests, which mock all Infrahub interactions, integration tests confirm end-to-end behavior against a functional API.

Sources: dev/guidelines/testing.md:12-16, dev/guides/running-integration-tests.py:1-5

Architecture and Infrastructure

The integration suite relies on Docker to host the Infrahub services. Each test class manages its own container lifecycle to ensure isolation and amortize the cost of container startup.

Test Layering

The project distinguishes between two test layers based on performance and dependencies:

Feature	Unit Tests	Integration Tests
Marker	Default (not integration)	@pytest.mark.integration
Environment	Local (No Docker)	Docker Required
Infrahub	Mocked Client	Live Container
Duration	Seconds	Minutes per class
Focus	Logic, Validation, Error Paths	E2E Behavior, Schema Resolution

Sources: dev/guidelines/testing.md:7-16, pyproject.toml:68-71

Container Lifecycle

The system uses a class-scoped container strategy. A fresh Infrahub instance starts for each test class, seeds the required schema, and populates initial data.

Core Components and Fixtures

The integration framework is built upon base classes and fixtures defined in tests/integration/conftest.py.

Base Classes

• TestInfrahubDocker: Provided by infrahub-testcontainers, managing the Docker lifecycle.
• NornirInfrahubIntegration: The project-specific base class that inherits from TestInfrahubDocker and provides standard fixtures for the Nornir plugin.

Essential Fixtures

• infrahub_address: A class-scoped fixture returning the URL of the running Infrahub container (e.g., http://localhost:{port}).
• bootstrap: An autouse fixture that loads the base SCHEMA and creates initial platforms, sites, IP addresses, and devices.
• TEST_TOKEN: The administrative token used for authentication, derived from PROJECT_ENV_VARIABLES["INFRAHUB_TESTING_INITIAL_ADMIN_TOKEN"].

Sources: tests/integration/conftest.py:58-69, dev/guides/running-integration-tests.md:27-38

Data Bootstrapping

The bootstrap fixture establishes a predictable state for testing. It populates the graph database with a standard set of nodes and relationships.

Default Test Schema

The integration environment includes the following node types by default:

• InfraPlatform: Defines device operating systems (e.g., eos, junos).
• InfraSite: Defines locations (e.g., chicago, nyc).
• InfraIPAddress: Defines host addresses (e.g., 10.0.0.1/32).
• InfraDevice: The primary host node containing relationships to platform, site, and primary address.
• CoreStandardGroup: Used to test Nornir group membership logic.

Sources: tests/integration/conftest.py:10-55

Data Flow for Setup

Execution Guidelines

Integration tests are explicitly excluded from the default pytest execution to prevent accidental Docker dependencies.

Command Reference

• Run all integration tests: pytest -m integration
• Run a specific file: pytest -m integration tests/integration/test_inventory.py
• Run a specific class: pytest -m integration tests/integration/test_inventory.py::TestInventoryBasic

Sources: dev/guides/running-integration-tests.md:14-25, AGENTS.md:46-51

Authentication

Do not hardcode tokens in test files. Authentication must use the TEST_TOKEN imported from the integration configuration to ensure compatibility with the container's randomized initial admin token.

from .conftest import TEST_TOKEN
# Use TEST_TOKEN when initializing InfrahubClientSync or InfrahubInventory

Sources: tests/integration/conftest.py:7, dev/guides/running-integration-tests.md:33-38

Testing File Objects and Artifacts

Specialized integration tests handle file operations and generated artifacts. These often require layering additional schema on top of the base bootstrap.

CoreFileObject Testing

Integration tests for upload_file_object and download_file_object verify idempotency and checksum comparison. These tests use a custom schema inheriting from CoreFileObject and perform real uploads/downloads to the container's object store.

Extending Schema

If a test requires specific nodes not present in the base bootstrap, define a class-scoped fixture that depends on bootstrap and calls client.schema.load().

Sources: tests/integration/test_file_object.py:48-55, dev/guides/running-integration-tests.md:49-52

Integration tests and Testcontainers ensure the nornir-infrahub plugin correctly interacts with the Infrahub API, handling complex scenarios like branch routing and multi-hop schema mappings that unit tests cannot fully validate.