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.