Getting Started
Option A: Install the pytest plugin
The fastest way to start — install the plugin, run your tests, and DAGZ handles the rest.
1. Install
pip install dagz-pytest
Or with uv:
uv add dagz-pytest
2. Run your tests
pytest --dagz
On first run, DAGZ will:
- Prompt you to install
zb(the DAGZ runtime) if it's not already installed - Start a local daemon that stores test data on your machine
- Record function-level coverage for every test
All tests run as usual on this first pass — the result becomes your baseline.
3. Make a change and run again
pytest --dagz
This time, DAGZ compares your code against the baseline. Tests that don't depend on your changes are skipped:
dagz: 142 selected, 891 skipped (baseline: abc1234)
Option B: Install the CLI first
If you prefer to set up the runtime before running tests:
curl -LsSf https://dagz.run/zb/install.sh | sh
This installs the zb binary. Start the daemon:
zb up
Then run pytest --dagz in any project. The daemon is shared across all your repos.
Key pytest options
| Option | Description |
|---|---|
--dagz | Enable DAGZ test selection and coverage collection |
--dagz-select | Enable test selection only (skip coverage collection) |
--dagz-baseline | Force a specific baseline (by hash or latest) |
--dagz-full | Run all tests but still collect coverage (useful for building baselines) |
--dagz-explain | Print the selection trace for each selected test — shows why it was selected |
--dagz-workers N | Number of parallel worker processes (default: 60% of CPU cores) |
Configuration
DAGZ works with zero configuration. For customization, add a .dagz/config.yaml to your repo root:
# .dagz/config.yaml
project:
uri: [email protected]:your-org/your-repo.git
timezone: UTC
The uri identifies your project across runs. If omitted, DAGZ derives it from your git remote.
Feature flags
All enabled by default:
| Flag | What it does |
|---|---|
detect_new_overrides | Track method overrides in class hierarchies |
hires_registry_tracking | Per-entry precision for plugin registries |
collect_caches | Detect changes to cached values |
capture_terminal | Capture test stdout/stderr via PTY |
distributed_coverage | Track coverage across subprocesses |
collect_dynamic_imports | Capture imports inside functions |
Open the dashboard
Visit http://localhost:29111 to see test results, which tests were skipped and why, and performance trends over time.
What gets stored locally
All DAGZ data lives in ~/.dagz/local.env/:
| Directory | Contents |
|---|---|
clickhouse/data/ | Test results, coverage data, baselines |
kv/ | Dependency graph, code unit hashes |
web/web.log | Daemon log file |