pytest-airflow-in-a-box

pytest-airflow-in-a-box is a pytest plugin for testing Apache Airflow DAGs without a live Airflow deployment. It targets Airflow 3 and provides the package and plugin foundation for a small, typed testing surface.

The package auto-registers with pytest, creates an isolated metadata database, and provides typed fixtures for persisted Dags, DagRuns, task instances, sessions, and Dag bags.

Contents

• Quickstart
• Why not...
• Requirements
• Installation
• Documentation
• Development
• License

Quickstart

uv add --dev pytest-airflow-in-a-box
pip install pytest-airflow-in-a-box

from airflow.sdk import task


def test_dag(dag_maker):
    with dag_maker():

        @task
        def produce():
            return 21

        @task
        def consume(value):
            return value * 2

        consume(produce())

    result = dag_maker.run()

    assert result.success
    assert result.xcoms == {"produce": 21, "consume": 42}
    assert result.order == ["produce", "consume"]

pytest

dag_maker.run() executes every task in dependency order and returns an inert DagRunResult snapshot: states, xcoms, errors, order, and per-task access via result["task_id"]. Single tasks run with dag_maker.run_ti("produce"), and pytest_airflow_in_a_box.matchers supports one-expression bulk assertions like assert result == {"produce": succeeded(21), "consume": succeeded(42)}.

The pytest11 entry point registers the plugin automatically -- no pytest_plugins declaration needed. See the documentation site for the full dag_maker/run/run_ti surface, sessions, DB-free task execution, deferrable operators, the REST API fixture, and bundled smoke checks.

Why not...

• dag.test() -- Airflow's own built-in helper runs one Dag end to end, but it is not a pytest plugin: no fixtures, no isolated metadata database, no xdist parallelism, no REST API testing
• upstream tests_common -- the harness Airflow's own core test suite runs on; it targets testing Airflow itself, not published as a package for testing DAG-author code
• Flowminder pytest-airflow -- an inverse concept (runs pytest suites under Airflow, rather than testing DAGs under pytest) and unmaintained
• airflow-pytest-plugin -- generates JUnit-XML dashboards from DAG runs; not aimed at isolated, fixture-driven unit testing

Requirements

• CPython 3.10 through 3.14
• pytest 8 or newer
• Apache Airflow 3.1 or newer, below 4
• Linux or macOS for Airflow-backed tests

Apache Airflow does not support native Windows installations. Windows development should use WSL2 or the included devcontainer; platform-independent package checks alone do not imply full Windows Airflow support.

The released compatibility matrix is exercised against Airflow 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.5, 3.1.6, 3.1.7, 3.1.8, 3.2.0, 3.2.1, 3.2.2, and 3.3.0 across CPython 3.10 through 3.14 using Airflow's published constraints files.

Installation

uv add --dev pytest-airflow-in-a-box
pip install pytest-airflow-in-a-box

The pytest11 entry point loads the plugin automatically. Consumer projects do not need to add a pytest_plugins declaration.

The bundled pytest plugins are intentional runtime dependencies. pytest-xdist is part of the supported execution model: controller bootstrap state and worker-scoped artifacts are coordinated for parallel runs. pytest-timeout backs up Airflow's per-file Dag parse watchdog with a corpus-scaled deadline on every bundled smoke item, so whichever worker produces the shared corpus cannot wedge the test session outside the per-file parser boundary.

The plugin is inert on runs without Airflow-facing tests: session startup only prepares a disposable run directory and AIRFLOW__* environment variables. Airflow itself is imported and the metadata database migrated lazily, on the first test that carries a db_test/api_test marker or uses a database-backed plugin fixture. A pytest -k unrelated run in a shared venv never pays the Airflow import or migration cost. Tests that touch the metadata database directly (their own create_session calls, for example) without a plugin fixture must carry db_test to trigger initialization.

To disable the plugin entirely for a run:

pytest -p no:pytest_airflow_in_a_box

Documentation

Task execution, deferrable operators, DB-free execution, Variable/Connection seeding, structlog capture, Dag collection, configuration overrides, smoke tests, database backends and cleanup, the live REST API, markers, and diagnostics are all covered on the documentation site.

Development

uv sync
uv run prek install
make all

Run the GitHub Actions workflow locally on Linux with act:

act pull_request

act cannot reproduce native macOS or Windows behavior. See CONTRIBUTING.md for the full contribution workflow and the issue tracker for open work.

License

Apache License 2.0. See LICENSE, NOTICE, and PROVENANCE.md.