pytest-airflow-in-a-box

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

Did you verify the DAG?

Import and callable tests do not exercise trigger rules, branch skips, rendered templates, connection resolution, or operator serialization. pytest-airflow-in-a-box tests those seams in pytest, before deployment -- no scheduler, webserver, or live Airflow environment required.

For teams that own Airflow behavior: Dags in a repository, custom operators, hooks, sensors, connection types, live REST API integrations, or an Airflow 2-to-3 migration. 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.

GitHub Action

nredd/pytest-airflow-in-a-box/action@v0 provisions a constraints-pinned Airflow environment; your workflow still runs pytest.

name: Airflow tests

on: [pull_request]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: nredd/pytest-airflow-in-a-box/action@v0
        id: airflow-env
        with:
          airflow-version: "3.3.1"
          python-version: "3.13"
      - run: ${{ steps.airflow-env.outputs.python-path }} -m pytest

The action does not run tests, cache packages, upload artifacts, or start Docker. See GitHub Actions and reports for every input and output, report uploads, version matrices, and pinning.

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.