fix

---
name: fix
description: Use when a Playwright test fails or passes intermittently. Diagnose using taxonomy and apply targeted fixes.
category: Engineering
version: 1.0.0
tools: []
---

# Fix Failing or Flaky Tests

Diagnose and fix Playwright tests using a systematic taxonomy.

## Reproduce the Failure

Run the test:
```bash
npx playwright test <file> --reporter=list
```

If test passes, run burn-in:
```bash
npx playwright test <file> --repeat-each=10
```

If still passes, try parallel:
```bash
npx playwright test --fully-parallel --workers=4 --repeat-each=5
```

Capture trace:
```bash
npx playwright test <file> --trace=on --retries=0
```

## Categorize the Failure

| Category | Symptom | Diagnosis |
|---|---|---|
| Timing/Async | Intermittent everywhere | `--repeat-each=20` reproduces locally |
| Test Isolation | Fails in suite, passes alone | `--workers=1` passes |
| Environment | Fails in CI, passes locally | Compare screenshots/traces |
| Infrastructure | Random, no pattern | Browser internals error |

## Apply Targeted Fixes

**Timing/Async:**
- Replace `waitForTimeout()` with web-first assertions
- Add `await` to all Playwright calls
- Wait for network responses before asserting
- Use `toBeVisible()` before interactions

**Test Isolation:**
- Remove shared mutable state
- Create test data per-test via API/fixtures
- Use unique identifiers (timestamps, random strings)
- Check for database leaks

**Environment:**
- Match viewport sizes (local vs CI)
- Account for font rendering differences
- Use Docker locally to match CI
- Check timezone-dependent assertions

**Infrastructure:**
- Increase timeout for slow runners
- Add `retries: 2` in CI config
- Check browser OOM (reduce workers)
- Verify browser dependencies installed

## Verify the Fix

Run 10x to confirm stability:
```bash
npx playwright test <file> --repeat-each=10
```

All 10 must pass.

## Prevent Recurrence

- Add to CI with `retries: 2`
- Enable `trace: 'on-first-retry'` in config
- Document fix pattern in test conventions