Pytest Plugin for Infrahub

Relevant source files

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

• infrahub_sdk/pytest_plugin/AGENTS.md
• infrahub_sdk/pytest_plugin/plugin.py
• infrahub_sdk/pytest_plugin/models.py
• pyproject.toml
• AGENTS.md
• tasks.py

The Pytest Plugin for Infrahub provides a specialized testing framework for validating Infrahub resources using YAML-based test definitions. It enables network automation engineers and developers to verify Checks, GraphQL queries, and Transformations (both Jinja2 and Python) within the Infrahub ecosystem.

The plugin automates the discovery and execution of tests defined in YAML files, abstracting the complexity of the underlying Infrahub API and resource processing. It integrates directly into the standard pytest workflow as an entry point, allowing users to run infrastructure tests alongside standard Python unit and integration tests.

Sources: infrahub_sdk/pytest_plugin/AGENTS.md:1-7, pyproject.toml:44-45, AGENTS.md:5-15

Plugin Architecture and Project Structure

The plugin is organized into specialized modules handling hooks, data models, and test item logic. It is registered via the pytest11 entry point as pytest-infrahub.

The diagram shows the internal structure of the pytest plugin and its entry point registration.
Sources: infrahub_sdk/pytest_plugin/AGENTS.md:23-29, pyproject.toml:44-45

Core Components

Component	Description
plugin.py	Contains Pytest hooks such as pytest_collect_file to identify and load test files.
loader.py	Handles YAML loading and maintains the ITEMS_MAPPING for resource types.
models.py	Defines Pydantic schemas that validate the structure of YAML test files.
items/	Contains implementations for specific test types (e.g., check.py).
InfrahubItem	The base class from which all custom test item implementations must inherit.

Sources: infrahub_sdk/pytest_plugin/AGENTS.md:23-29, infrahub_sdk/pytest_plugin/AGENTS.md:32-41

YAML Test Configuration

Tests are defined in YAML files using the infrahub_tests top-level key. Each test entry specifies the resource type, the name of the resource to test, and a list of specific test cases with defined inputs and expected outputs.

infrahub_tests:
  - resource: Check
    resource_name: my_check
    tests:
      - name: test_success_case
        spec:
          kind: check-smoke
        input:
          data: {"key": "value"}
        output:
          passed: true

Sources: infrahub_sdk/pytest_plugin/AGENTS.md:9-19

Supported Resource Types and Test Kinds

The plugin supports four primary resource types, each associated with specific test "kinds" that determine the validation logic applied (Smoke, Unit, or Integration).

Resource	Smoke Kind	Unit Kind	Integration Kind
Check	check-smoke	check-unit-process	check-integration
GraphQL	graphql-query-smoke	N/A	graphql-query-integration
Jinja2	jinja2-transform-smoke	jinja2-transform-unit-render	jinja2-transform-integration
Python	python-transform-smoke	python-transform-unit-process	python-transform-integration

Sources: infrahub_sdk/pytest_plugin/AGENTS.md:21-26

Execution Flow

The plugin follows the standard pytest lifecycle, intercepting the collection phase to include YAML files and then executing the custom runtest logic defined in the item classes.

The sequence diagram illustrates the flow from file collection to test execution and assertion.
Sources: infrahub_sdk/pytest_plugin/AGENTS.md:32-41, infrahub_sdk/pytest_plugin/plugin.py

Implementation Requirements

When extending the plugin with new test items, developers must:

1. Create a class in the items/ directory that inherits from InfrahubItem.
2. Implement runtest(), which typically processes the test input and asserts against the expected output.
3. Register the item in the ITEMS_MAPPING located in loader.py.

Sources: infrahub_sdk/pytest_plugin/AGENTS.md:32-43

Integration and Usage

The plugin is part of the infrahub-sdk package and is intended to be used with the uv package manager or standard pytest invocations.

• Installation: uv sync --all-groups --all-extras installs the plugin along with all dependencies.
• Execution: uv run pytest tests/unit/ or uv run pytest tests/integration/ will automatically trigger the plugin if YAML test files are discovered in the search paths.

Sources: pyproject.toml:44-45, AGENTS.md:18-26, tasks.py:270-280

The plugin relies on the core SDK dependencies, including pydantic >= 2.0 for model validation and httpx for potential integration testing against Infrahub instances.

Sources: pyproject.toml:21-25, AGENTS.md:38

Summary

The Pytest Plugin for Infrahub bridges the gap between static resource definitions and automated validation. By utilizing Pydantic-backed YAML schemas and a modular item-mapping architecture, it allows users to define infrastructure tests declaratively. This system ensures that Checks and Transforms function correctly across smoke, unit, and integration levels, maintaining the integrity of the Infrahub data model.