| name | detox |
| description | Hunt down and fix flaky tests. Use when a test suite fails intermittently, CI needs re-runs to go green, or the user wants to know which tests are flaky versus genuinely broken — and why. |
Detox
A flaky test is worse than a missing test: it trains everyone to ignore red. Your job is to separate flaky from broken, diagnose each flake's root cause class, and fix the cause — never the symptom.
Banned fixes
Retry wrappers, longer sleeps, and skip are not fixes; they are how flakes become permanent residents. The only acceptable retry is around a call to a genuinely external system the test cannot control — and that usually means the test should be mocking it instead.
Phase 1 — Census
Run the full suite repeatedly — default 5 runs, more if runs are cheap — and build a per-test pass/fail matrix.
- Fails every run → broken, not flaky. Report separately; out of scope unless asked.
- Fails some runs → flaky. This is the target list, ranked by failure rate.
- Record conditions per run: ordering, parallelism, seed, timing — the variance between a passing and failing run often names the culprit by itself.
Phase 2 — Diagnose each flake
Isolate, then classify. Standard experiments:
| Experiment | If behavior changes → |
|---|
| Run the test alone vs. after the full suite | Shared state / test-order dependence |
| Run the suite in random order / different parallelism | Order dependence, resource contention (ports, files, DB rows) |
| Run with a fixed seed / frozen clock | Unseeded randomness, time-of-day or timezone dependence |
| Run repeatedly in a tight loop | Race conditions, timing assumptions, hardcoded timeouts |
| Run with network blocked / observed | Real network calls hiding in a "unit" test |
Read the failing assertion under each hypothesis: a flake almost always belongs to one of six families — shared state, ordering, timing/races, unseeded randomness, clock/timezone, external systems (network, filesystem, ports).
Phase 3 — Fix the cause
Match the fix to the family: proper setup/teardown isolation for shared state; explicit awaiting or synchronization points instead of sleeps for races; injected/frozen clocks; seeded randomness; mocks or test doubles for external systems; per-test unique resources (temp dirs, ephemeral ports) for contention. The fix should make the test deterministic, not tolerant.
Phase 4 — Prove it
A fix isn't proven by one green run. Run the fixed test 20+ times, including under the conditions that made it fail (full-suite ordering, parallelism, tight loop). Then run the whole suite to confirm the fix didn't shift the flake elsewhere.
Phase 5 — Report
Write FLAKES.md: per test — failure rate before, root-cause family, the experiment that proved it, the fix, runs-passed after. Plus a short "flake debt" section: patterns in the codebase likely to breed the same families again (a shared fixture, a real HTTP client in unit tests), so the next flake gets prevented rather than hunted.
