pytest-dag

Documentation: https://pytest-dag.readthedocs.io/en/latest/

pytest-dag is a pytest plugin for dependency-aware test execution.

It lets tests declare dependencies, builds a DAG, runs tests in topological order, and skips downstream tests when required dependencies fail.

Installation

pip install pytest-dag

Quick Start

import pytest

def test_a():
    assert True

@pytest.mark.dag(depends=["test_a"])
def test_b():
    assert True

@pytest.mark.dag(depends=["test_b"])
def test_c():
    assert True

@pytest.mark.dag(depends=["test_b"])
def test_d():
    assert True

Expected run order:

test_a -> test_b -> (test_c, test_d)

If test_a fails, dependent tests are skipped with a clear reason:

SKIPPED pytest-dag: blocked by test_file.py::test_a (FAILED)

Marker Syntax

# Single dependency (string)
@pytest.mark.dag(depends="test_login")
def test_profile():
    ...

# Multiple dependencies (list)
@pytest.mark.dag(depends=["test_login", "test_db_connect"])
def test_dashboard():
    ...

# Cross-file dependency (full nodeid)
@pytest.mark.dag(depends=["tests/auth/test_auth.py::test_login"])
def test_profile():
    ...

YAML DAG (for larger test suite, where it really shine!)

For larger suites, you can define dependencies in YAML instead of (or in addition to) markers.

pyproject.toml:

[tool.pytest.ini_options]
dag_file = "tests/dag.yaml"

tests/dag.yaml:

nodes:
  - id: tests/test_flow.py::test_a
  - id: tests/test_flow.py::test_b
    depends: [tests/test_flow.py::test_a]
  - id: tests/test_flow.py::test_c
    depends: [tests/test_flow.py::test_b]

Marker dependencies and YAML dependencies are unioned.

CLI Options

Examples:

# Cascade skipping (skip dependents when a dependency fails or is skipped)
pytest --dag-block-on-outcomes fail,skip

# Print computed graph for debugging
pytest --dag-print-graph

Migrating from pytest-dependency

If your suite uses pytest.mark.dependency(...) markers, the built-in migration tool scans your tests, emits a dag.yaml, and removes the old markers from source files in one step.

Example workflow:

# Step 1: Preview what will be generated (no files written)
pytest --migrate-from-pytest-dependency --migrate-dry-run

# Step 2: Run the full migration (writes dag.yaml, removes old markers)
pytest --migrate-from-pytest-dependency --dag-file-out tests/dag.yaml

Tiers

pytest-dag is free to use with no key required. A pro license unlocks additional features.

Activating pro

Set the key received from the purchase page via environment variable (recommended for CI):

export PYTEST_DAG_LICENSE_KEY=<your-license-key>
pytest --dag-report-out report.html --dag-workers 4

Or via CLI flag or key file:

pytest --pytest-dag-license-key <your-license-key>
pytest --pytest-dag-license-key-file /path/to/key.txt

License verification is done locally — no network calls are made.

Purchase: https://slrsoft.ca/app/pytest-dag/purchase
Support: support@slrsoft.ca

Viewing Skip Reasons

Use -v -rs to see exact skip reasons:

pytest -v -rs

Example summary:

SKIPPED [2] pytest-dag: blocked by test_demo.py::test_login (FAILED)
SKIPPED [1] test_demo.py:104: feature not yet implemented

pytest-xdist Compatibility

On the free tier, pytest-dag automatically disables pytest-xdist (-n) to preserve DAG ordering correctness, and prints a warning.

On the pro tier, use --dag-workers N for native DAG-aware parallelism.

If xdist is installed but -n is not passed, behaviour is unchanged.

Troubleshooting

plugins: ... dag-0.1.0 (not pytest-dag-0.1.0)

This is normal. Pytest shortens plugin names in output by dropping the pytest- prefix.

Plugin not loading in a virtualenv

If which pytest points to a global executable after activating a venv, use:

python -m pytest ...

This guarantees the venv interpreter and installed plugin are used.

License

Proprietary. Copyright (c) 2026 SLR Software Solutions Inc.

See the license terms in the repository LICENSE file.

Licensing inquiries: support@slrsoft.ca