Pytest Failure Triage Cheat Sheet
Use this one-page flow to move from a failing test to verified root cause quickly. Full walkthrough: Python Test Failures Triage with Pytest.
| Goal | Command | Notes |
|---|
| Run single failing test | pytest -vv tests/path.py::test_case -x --maxfail=1 | Keep scope minimal first |
| Run one parameterized case | pytest -vv tests/path.py::test_case[param] -x | Avoid mixed signals |
| Stop on first failure | pytest -x --maxfail=1 | Fast feedback loop |
| Show local variables in traceback | pytest -vv -l | Useful for assertion context |
| Drop into debugger on fail | pytest -vv --pdb | Inspect runtime state immediately |
| Signal | Likely Cause | First Command | Next Check |
|---|
ModuleNotFoundError | Env or path mismatch | python --version | pip freeze, sys.path |
AssertionError | Behavior or expected output drift | pytest -vv -l | Compare outputs in Diff Checker |
| Intermittent pass/fail | Flaky state, timing, randomness | for i in {1..30}; do pytest ...; done | Fix seed/time/shared state |
| Timeout/hang | Wait condition or deadlock | pytest -vv -x | Add strict timeout + logs |
| Check | Command | Target |
|---|
| Python interpreter | which python && python --version | Match CI major/minor version |
| Pytest/plugin versions | pytest --version | No hidden plugin drift |
| Dependency lock parity | pip freeze | rg -n "pytest|pluggy" | Critical package parity |
| Import path visibility | python -c "import sys; print('\\n'.join(sys.path))" | Expected project path present |
| Package resolution | python -c "import pkg; print(pkg.__file__)" | Correct module source |
| Pattern | Command | Why |
|---|
| Repeat test rapidly | for i in {1..30}; do pytest -q tests/path.py::test_case || break; done | Confirm intermittency |
| Fix hash randomness | PYTHONHASHSEED=0 pytest -vv tests/path.py::test_case | Control dict/set iteration variance |
| Order-sensitive suite run | pytest -vv tests/path -x | Expose state leakage between tests |
| Capture failing artifacts | pytest -vv --maxfail=1 > fail.log 2>&1 | Preserve exact failure evidence |
| Requirement | Verification |
|---|
| Root cause is explicit | One sentence in PR: cause + evidence |
| Original repro command passes | Run same command used in triage start |
| CI-like scope passes | Run relevant directory/module test subset |
| Prevention guard added | Fixture reset, deterministic seed, or stricter assertion |