Fix a Flaky Test
Systematic approach to diagnosing and fixing intermittent test failures
CLAUDE.md
When fixing a flaky test:
- Run the test 20+ times in isolation to confirm it’s actually flaky and identify the failure pattern.
- Check for timing issues: race conditions, missing awaits, fixed sleep timers instead of proper waits.
- Check for shared state: does the test depend on state from a previous test or a global variable?
- Check for external dependencies: network calls, file system state, system clock, random values.
- Check for order dependence: run the test suite in random order to see if it still fails.
- Fix the root cause. If the fix isn’t clear, quarantine the test and investigate offline — don’t let it erode trust in the suite.
Copy this workflow into your CLAUDE.md or agent config file so your agent follows this process automatically.