pytest-dag 3.1.4

A pytest plugin that enforces test execution order via a dependency DAG

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

Option	Default	Description
--dag-block-on-outcomes OUTCOMES	fail	Outcomes that block dependents: fail, skip, xfail, error
--dag-print-graph	off	Print DAG order and edges after collection
--pytest-dag-license-key	unset	Provide license key directly
--pytest-dag-license-key-file	unset	Read license key from file

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.

Option	Default	Description
--migrate-from-pytest-dependency	off	Run preflight validation, emit dag.yaml, remove pytest.mark.dependency markers from source, then exit without running tests
--dag-file-out PATH	tests/dag.yaml	Output path for the generated YAML file
--migrate-dry-run	off	Preview the generated YAML without writing any files

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

License Setup

pytest-dag may require a license key depending on current license policy.

Provide a license key using one of:

• Environment variable: PYTEST_DAG_LICENSE_KEY
• CLI value: --pytest-dag-license-key
• Key file: --pytest-dag-license-key-file

Examples:

export PYTEST_DAG_LICENSE_KEY=pd-XXXX-XXXX-XXXX-XXXX
python -m pytest -v -rs

pytest --pytest-dag-license-key-file /path/to/key.txt -v -rs

Purchase or renew:

• https://slrsoft.ca/app/pytest-dag/purchase

Support:

• [e-mail]

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

pytest-dag is not compatible with pytest-xdist parallel execution (-n). To preserve DAG correctness, the plugin automatically disables xdist when it is active and prints a warning.

If xdist is installed but -n is not passed, nothing is changed.

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: [e-mail]