Airflow Local Debug

The problem it solves

The standard Airflow development loop is slow: write code → deploy → wait for the scheduler → dig through logs. airflow-local-debug closes that loop: run your DAG locally with one command or function call and see the result immediately.

What it does

• Deterministic local execution — drives dag.test() / dag.run() directly, bypassing the scheduler

• Fail-fast mode — custom scheduling loop that zeroes out retries and stops on the first failed task

• Partial runs — --task, --start-task, --task-group to execute a subgraph instead of the full DAG

• Task mocks — replaces execute() on selected operators via a JSON/YAML rules file, matched by task_id, glob, or operator class

• Watch mode — monitors files for changes and re-runs automatically, resuming from the last failed task

• XCom collection — dumps all XCom values after a run to JSON

• DAG graph — renders ASCII and SVG graphs before execution

• Run reports — writes report.md, result.json, tasks.csv, junit.xml to a configurable output directory

• Plugin API — before_task / after_task / on_task_error hooks for custom instrumentation

• pytest integration — airflow_local_runner fixture for DAG-level tests

• Airflow 2 & 3 support — three execution backends with automatic version detection

Usage

# At the bottom of any DAG file if __name__ == "__main__": from airflow_local_debug import debug_dag debug_dag(dag) # Or via CLI airflow-debug-run my_dag.py --start-task transform --fail-fast airflow-debug-run my_dag.py --watch