pytest-dev
Produce high-signal, low-flake, fast pytest suites and CI configs, with an
explicit focus on measurable wins (runtime, flake rate, coverage quality).
Default workflow
- Classify the tests
- Unit: pure functions, no I/O (preferred)
- Integration: DB/filesystem/multiprocess, slower but valuable
- System/E2E: external services or UI, keep minimal and well-gated
- Identify boundaries
- Time/clock, randomness, network, filesystem, DB, env vars, global state
- Pick the lightest seam
- Prefer fakes/stubs over deep mocks; prefer dependency injection over
patching internals
- Make it deterministic
- Control time, seeds, tmp dirs; avoid order dependencies
- Measure before optimizing
- Collection time vs runtime; quantify with
--durations + a single baseline
- Harden for CI
- Enforce marker discipline, strict config, timeouts, isolation for parallel
Quick commands
Use python3 by default. If the project uses uv, prefer uv run python.
- Smallest repro:
python3 -m pytest path/to/test_file.py -q
- First failure only:
python3 -m pytest -x --maxfail=1
- Find slow tests:
python3 -m pytest --durations=20 --durations-min=0.5
- Emit JUnit for CI:
python3 -m pytest --junitxml=reports/junit.xml
- Parallelize on one machine (xdist):
python3 -m pytest -n auto --dist load
Optimization playbook (high ROI)
- Reduce collection scope (
testpaths, norecursedirs, avoid importing
heavy modules at import time).
- Fix fixture scoping (move expensive setup up-scope; ensure isolation).
- Eliminate sleeps and retries (poll with timeouts; mock time).
- Parallelize safely (xdist; isolate worker resources: tmp/db ports).
- Shard in CI (split test files by historical timings; keep shards balanced).
Use the bundled references
Read these when needed (keep SKILL.md lean):
references/pytest_core.md: fixtures, markers, parametrization, strict mode,
TOML config, subtests (pytest 9.x).references/plugins.md: plugin selection + usage patterns.references/performance.md: collection/runtime profiling and speedups.references/ci_github_actions.md: sharding, artifacts, caching, concurrency.
Use the bundled scripts
scripts/junit_slowest.py: report slowest tests/files from JUnit XML.scripts/junit_split.py: split test files into N shards using JUnit timings.scripts/run_pytest_filelist.py: run pytest for a list of test files.
Quality gates
- Tests pass in a clean environment (no hidden dependency on local state).
- No network/time dependency without explicit control.
- Parallel-safe or explicitly marked/serialized.
- CI emits machine-readable artifacts when relevant (JUnit, coverage).
1---2name: pytest-dev3description: World-class pytest engineer for Python: write/refactor tests, fix flakiness, design fixtures/markers, add coverage, speed up suites (collection/runtime), and optimize CI (GitHub Actions sharding, xdist parallelism, caching). Use when asked about pytest best practices, pytest 9.x features (subtests, strict mode, TOML config), pytest plugins (xdist/cov/asyncio/mock/httpx), or test performance/CI tuning.4---5
6# pytest-dev
7
8Produce **high-signal, low-flake, fast** pytest suites and CI configs, with an
9explicit focus on **measurable wins** (runtime, flake rate, coverage quality).
10
11## Default workflow
12
131. **Classify the tests**
14 - Unit: pure functions, no I/O (preferred)
15 - Integration: DB/filesystem/multiprocess, slower but valuable
16 - System/E2E: external services or UI, keep minimal and well-gated
172. **Identify boundaries**
18 - Time/clock, randomness, network, filesystem, DB, env vars, global state
193. **Pick the lightest seam**
20 - Prefer fakes/stubs over deep mocks; prefer dependency injection over
21 patching internals
224. **Make it deterministic**
23 - Control time, seeds, tmp dirs; avoid order dependencies
245. **Measure before optimizing**
25 - Collection time vs runtime; quantify with `--durations` + a single baseline
266. **Harden for CI**
27 - Enforce marker discipline, strict config, timeouts, isolation for parallel
28
29## Quick commands
30
31Use `python3` by default. If the project uses `uv`, prefer `uv run python`.
32
33- Smallest repro: `python3 -m pytest path/to/test_file.py -q`
34- First failure only: `python3 -m pytest -x --maxfail=1`
35- Find slow tests: `python3 -m pytest --durations=20 --durations-min=0.5`
36- Emit JUnit for CI: `python3 -m pytest --junitxml=reports/junit.xml`
37- Parallelize on one machine (xdist): `python3 -m pytest -n auto --dist load`
38
39## Optimization playbook (high ROI)
40
411. **Reduce collection scope** (`testpaths`, `norecursedirs`, avoid importing
42 heavy modules at import time).
432. **Fix fixture scoping** (move expensive setup up-scope; ensure isolation).
443. **Eliminate sleeps and retries** (poll with timeouts; mock time).
454. **Parallelize safely** (xdist; isolate worker resources: tmp/db ports).
465. **Shard in CI** (split test files by historical timings; keep shards balanced).
47
48## Use the bundled references
49
50Read these when needed (keep SKILL.md lean):
51
52- `references/pytest_core.md`: fixtures, markers, parametrization, strict mode,
53 TOML config, subtests (pytest 9.x).
54- `references/plugins.md`: plugin selection + usage patterns.
55- `references/performance.md`: collection/runtime profiling and speedups.
56- `references/ci_github_actions.md`: sharding, artifacts, caching, concurrency.
57
58## Use the bundled scripts
59
60- `scripts/junit_slowest.py`: report slowest tests/files from JUnit XML.
61- `scripts/junit_split.py`: split test files into N shards using JUnit timings.
62- `scripts/run_pytest_filelist.py`: run pytest for a list of test files.
63
64## Quality gates
65
66- Tests pass in a clean environment (no hidden dependency on local state).
67- No network/time dependency without explicit control.
68- Parallel-safe or explicitly marked/serialized.
69- CI emits machine-readable artifacts when relevant (JUnit, coverage).
majiayu000