pytest-airflow-in-a-box

Your Dag files import. Your task callables pass. Production still breaks.

Well, you never really verified the DAG

Trigger rules, branch skips, rendered templates, connection resolution, and operator serialization remain untested until deployment. This plugin runs those seams in pytest, in your repo's own CI, with no scheduler, webserver, or ~/airflow.

For a team owning a dags/ repo on Airflow 3 that writes its own operators, hooks, sensors, and connection types -- deployed by someone else (MWAA, Composer, Astro, self-hosted). If your repo is 100% stock operators, dag.test() plus a DagBag import test is enough; the full list is on the documentation site.

Already have a DagBag import test and a pile of task.function(...) calls? Here is exactly where they stop, and why not dag.test(), DebugExecutor, or your own conftest.py.

Quickstart

def test_my_dag(dag_bag, run_dag):
    dag = dag_bag.dags["my_dag_id"]

    result = run_dag(dag)

    assert result.success
    assert result.order == ["extract", "load"]

pytest --dag-folder=dags

run_dag proves your real file, under its real dag_id, actually finishes in the states you expect. dag_bag parses the folder once per worker process, and result.order records execution order rather than graph topology. In-test Dags (dag_maker), single operators without a database (run_task), and matchers are in the Quickstart.

Installation

uv add --dev "pytest-airflow-in-a-box[airflow3]"

The plugin does not depend on Airflow directly: the Airflow 2.x monolith and the 3.x core both install under the name apache-airflow, so a hard plugin pin would corrupt whichever family you did not choose. The airflow3 extra pins apache-airflow>=3.1,<4, matching the dependency restriction in pyproject.toml. Projects that already pin Airflow themselves -- for example through Airflow's published constraints files -- install the plugin bare. Every extra and common combination is listed under Dependencies and extras.

In CI, nredd/pytest-airflow-in-a-box/action@v0 provisions a constraints-pinned environment -- see The GitHub Action.

Requirements

• CPython 3.10 through 3.14, pytest 8 or newer
• Apache Airflow 3.1 or newer, below 4; or a certified Airflow 2 release from 2.7 through 2.11
• Linux or macOS. Airflow has no native Windows support -- use WSL2 or the devcontainer

Which Airflow and Python combinations are actually exercised in CI, and what the 2.x tier does and does not cover, are stated once in Compatibility and certification. After installing, pytest --airflow-doctor tells you whether your own pin works.

What ships

Typed fixtures, grouped by the job:

Every fixture, its return type, and its scope: Fixtures. Markers are listed in Markers.

Also in the box: corpus smoke checks (--airflow-smoke), a disposable metadata database, an isolated AIRFLOW_HOME, report artifacts that survive -n auto, a GitHub Action, and an Airflow 2-to-3 migration toolkit fronted by the airflow-migration-diff console script.

Documentation

The documentation site follows the reader, one deep link per stage:

• Whose fail is it anyway? -- what earns a test
• The fidelity ladder -- which rung to stand on, and what each one costs
• Smoke Tests -- properties of the whole corpus
• Checking components -- validate Airflow extension points before registration
• Airflow 2->3 Migration -- arrive migrating, leave with a suite
• Under the hood -- what _compat/ absorbs, and why

Contributing, the local gate, and running CI with act: CONTRIBUTING.md and Developing this plugin.

License

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