6.4Troubleshooting Guides

Troubleshooting guides document common issues and their solutions. They save hours of debugging by capturing solutions that would otherwise live only in someone's head.

Troubleshooting Guide Format

# Troubleshooting: [System or Area]

## Symptom: [What the person observes]

### Possible Cause 1: [Most likely cause]
**How to verify:** [Steps to confirm this is the cause]
**Fix:** [Steps to resolve]

### Possible Cause 2: [Second most likely cause]
**How to verify:** [Steps to confirm]
**Fix:** [Steps to resolve]

### If None of the Above Work
Escalate to [team/person] with the following information:
- [What to include in the escalation]

Example: Flaky Test Troubleshooting

# Troubleshooting: Flaky E2E Tests

## Symptom: A test passes locally but fails in CI

### Possible Cause 1: Timing issue
**How to verify:** Add a `console.log(Date.now())` before the
failing assertion. Check if the element is rendering later in CI.
**Fix:** Add an explicit wait: `await page.waitForSelector('.element')`
Do NOT use `page.waitForTimeout()` as it masks the real issue.

### Possible Cause 2: Screen size difference
**How to verify:** Check the viewport size in CI config vs local.
CI runs at 1280x720; local may be different.
**Fix:** Set viewport explicitly in the test or test config.

### Possible Cause 3: Test data dependency
**How to verify:** Run the test in isolation (`--grep "test name"`).
If it passes alone but fails in the suite, another test is
modifying shared data.
**Fix:** Ensure each test creates its own data and cleans up.

### Possible Cause 4: Parallel execution race condition
**How to verify:** Run with `--workers=1`. If it passes, the
issue is parallelism-related.
**Fix:** Isolate test data per worker or use test-level locks.