Fix Failing or Flaky Tests

Input

$ARGUMENTS

• A test file path:

  e2e/login.spec.ts

• A test name:

  "should redirect after login"

• A description:

  "the checkout test fails in CI but passes locally"

Steps

1. Reproduce the Failure

npx playwright test <file> --reporter=list

npx playwright test <file> --repeat-each=10 --reporter=list

npx playwright test --fully-parallel --workers=4 --repeat-each=5

2. Capture Trace

npx playwright test <file> --trace=on --retries=0

/debug

3. Categorize the Failure

flaky-taxonomy.md

--repeat-each=20

--workers=1 --grep "test name"

4. Apply Targeted Fix

• Replace

  waitForTimeout()

  with web-first assertions
• Add

  await

  to missing Playwright calls
• Wait for specific network responses before asserting
• Use

  toBeVisible()

  before interacting with elements

• Remove shared mutable state between tests
• Create test data per-test via API or fixtures
• Use unique identifiers (timestamps, random strings) for test data
• Check for database state leaks

• Match viewport sizes between local and CI
• Account for font rendering differences in screenshots
• Use

  docker

  locally to match CI environment
• Check for timezone-dependent assertions

• Increase timeout for slow CI runners
• Add retries in CI config (

  retries: 2

  )
• Check for browser OOM (reduce parallel workers)
• Ensure browser dependencies are installed

5. Verify the Fix

npx playwright test <file> --repeat-each=10 --reporter=list

6. Prevent Recurrence

• Add to CI with

  retries: 2

  if not already
• Enable

  trace: 'on-first-retry'

  in config
• Add the fix pattern to project's test conventions doc

Output

• Root cause category and specific issue
• The fix applied (with diff)
• Verification result (10/10 passes)
• Prevention recommendation