Workflow Testing

Fix a Flaky Test

Systematic approach to diagnosing and fixing intermittent test failures

testingflakydebugging
CLAUDE.md

When fixing a flaky test:

  1. Run the test 20+ times in isolation to confirm it’s actually flaky and identify the failure pattern.
  2. Check for timing issues: race conditions, missing awaits, fixed sleep timers instead of proper waits.
  3. Check for shared state: does the test depend on state from a previous test or a global variable?
  4. Check for external dependencies: network calls, file system state, system clock, random values.
  5. Check for order dependence: run the test suite in random order to see if it still fails.
  6. 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.

get crystl