Local Development Setup

Relevant source files

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

• dev/guides/local-development-setup.md
• AGENTS.md
• tasks.py
• pyproject.toml
• dev/guidelines/python.md
• dev/guidelines/git-workflow.md
• dev/guidelines/testing.md
• dev/guidelines/documentation.md

Local development for nornir-infrahub requires a specific environment to ensure compatibility between the Nornir framework and the Infrahub SDK. This repository uses uv for dependency management and invoke for task orchestration, providing a standardized workflow for linting, testing, and documentation generation.

Contributors must follow the sync-before-commit gate to maintain code quality. The environment supports two tiers of testing: fast unit tests that run in isolation and Docker-based integration tests that validate interactions with a live Infrahub stack.

Sources: dev/guides/local-development-setup.md:1-7, AGENTS.md:11-20, dev/guidelines/python.md:10-20

Environment Prerequisites

You must install the following core technologies before configuring the project:

Requirement	Version / Specification	Purpose
Python	>=3.10, <3.15	Core runtime for the plugin and SDK.
uv	Latest	Dependency and virtual environment management.
Docker	Running	Required for integration tests via infrahub-testcontainers.
Node.js & npm	Latest	Required for building and serving the Docusaurus documentation.

Sources: pyproject.toml:10, dev/guides/local-development-setup.md:9-15

Core Development Workflow

The development lifecycle follows a structured sequence from environment synchronization to quality gate validation.

The diagram shows the standard progression from initial setup to final contribution gates.

Initial Installation

1. Clone the repository to your local machine.
2. Run uv sync to create a virtual environment and install all dependencies in the dev group.
3. Activate the environment with source .venv/bin/activate or use uv run to execute commands.

Sources: dev/guides/local-development-setup.md:17-25, dev/guidelines/git-workflow.md:16-18

Quality Control and Tooling

nornir-infrahub enforces strict linting and formatting standards through invoke tasks. The tasks.py file defines these entry points, which wrap multiple underlying CLI tools.

Formatting

Run invoke format to standardize the codebase. This task executes:

• ruff format .: Formats Python files.
• ruff check . --fix: Automatically fixes fixable linting errors.
• rumdl fmt .: Formats Markdown files.

Sources: tasks.py:17-25, dev/guidelines/git-workflow.md:18-20

Linting Suite

The full suite is executed via invoke lint. It validates the project using the following tools:

Task	Underlying Tool	Target
lint-yaml	yamllint	Configuration files.
lint-ty	ty	Python type annotations.
lint-ruff	ruff	Python coding standards.
lint-pylint	pylint	Deep static analysis of nornir_infrahub.
lint-markdown	rumdl	Documentation structure.

Sources: tasks.py:28-66, dev/guides/local-development-setup.md:32-45

Testing Infrastructure

Tests are split into two distinct categories to balance speed and accuracy.

Unit Testing

Unit tests reside in tests/unit/. These tests are fast because they use MagicMock to simulate Infrahub interactions. They do not require Docker or network access.

• Execute with: pytest
• Default behavior: The pyproject.toml file configures addopts = "-m 'not integration'" to exclude integration tests by default.

Sources: pyproject.toml:72-76, dev/guidelines/testing.md:10-18

Integration Testing

Integration tests reside in tests/integration/. They validate end-to-end behavior against a live Infrahub instance.

• Requirement: Docker must be running.
• Mechanism: Inherits from NornirInfrahubIntegration, which uses infrahub-testcontainers to spin up a container per test class.
• Authentication: Uses the admin token from PROJECT_ENV_VARIABLES["INFRAHUB_TESTING_INITIAL_ADMIN_TOKEN"].
• Execute with: pytest -m integration

Sources: dev/guidelines/testing.md:55-65, dev/guides/local-development-setup.md:55-65

This diagram illustrates how unit tests remain local while integration tests bridge to a Docker-hosted Infrahub stack.

Documentation Development

The documentation site is built with Docusaurus and located in the docs/ directory.

Documentation Tasks

• Installation: invoke docs-install runs npm install inside the docs/ folder.
• Preview: invoke docs-serve starts a development server at http://localhost:3000 with live reload.
• Build: invoke docs-build creates a production-ready static site.
• Generation: invoke generate-docs parses Python docstrings and uses Jinja2 templates (plugin.mdx.j2) to generate Markdown files for the plugin reference.

Sources: tasks.py:69-106, dev/guidelines/documentation.md:10-25

Git Contribution Standards

Before pushing to a feature branch, you must ensure all gates pass.

• Pre-commit: Fast checks like ruff and rumdl are wired into git hooks via .pre-commit-config.yaml.
• Branching: All work targets the stable branch. Direct pushes to stable are prohibited.
• Secrets: Never commit tokens or secrets; use the provided test fixtures for authentication.

Sources: dev/guidelines/git-workflow.md:7-13, AGENTS.md:120-130

Local development setup is designed to be self-contained and reproducible. By utilizing uv for environment isolation and invoke for task automation, the project ensures that every contributor can validate their changes against the same quality and testing standards used in the CI pipeline.

Sources: dev/guides/local-development-setup.md:67-70