flaky-test-hunter

---
name: flaky-test-hunter
description: Finds and diagnoses flaky tests in a test suite. Use when tests pass locally but fail in CI, when a suite fails intermittently, or when the user asks to stabilise or de-flake their tests.
---

# Flaky test hunter

## When to use this
Tests pass locally but fail in CI, a suite fails intermittently, or the user
asks to stabilise their tests.

## Procedure
1. Establish the failure rate before changing anything. Run the suspect test in
   a loop and record how many runs in how many fail.
2. Classify the flake against [references/flake-taxonomy.md](references/flake-taxonomy.md).
3. Prove the cause by making the flake deterministic — force the ordering, freeze
   the clock, or pin the seed so the test fails every time.
4. Fix the cause, not the symptom.
5. Re-run the loop and show the new failure rate.

## Rules
- **Never** fix a flake by adding a sleep, a retry, or increasing a timeout.
  Those hide the defect and slow the suite permanently.
- A fix is not proven until the loop that used to fail passes repeatedly.
- If the flake is in the code under test rather than the test, say so plainly.

# Flake taxonomy

| Class | Signature | Typical fix |
| --- | --- | --- |
| Order dependence | Fails only when run after another test | Reset shared state in a hook |
| Real time | Fails near midnight, month end, or on slow CI | Inject and freeze the clock |
| Async leak | Assertion runs before the effect settles | Await the actual condition, not a timeout |
| Shared fixture | Parallel workers mutate one record | Namespace fixtures per worker |
| Network | Depends on a live third party | Record and replay, or stub at the boundary |
| Randomness | Unseeded random input | Pin the seed and log it on failure |