debug-test

SKILL.md

---
name: debug-test
description: Use when a Playwright test is failing. Diagnoses the root cause and applies a minimal fix. Requires the failing test file path and the full error output.
---

# Debug Test

## When to use

- When a Playwright test fails after generate-tests
- When running as part of `run-testing-session` pipeline (after generate-tests FAIL)
- When a previously passing test starts failing after a UI change

## Inputs

- Failing test file path
- Full error output from the test run
- `docs/playwright-spec-testing/exploration/[SCENARIO_SLUG].md` — original selectors
- `docs/playwright-spec-testing/test-plan.md` — scenario context
- `docs/playwright-spec-testing/project-context.md` — for baseURL

## What it does

Diagnose the failure and apply a minimal fix. Debug in this order:

1. **Is the app running?**
   ```bash
   curl [BASE_URL]
   ```
   If connection refused, report NEEDS_CONTEXT — the orchestrator must ask the user to start the app.

2. **Has the selector changed?**
   Open the browser, find the element, check if the selector in the test still matches.
   ```bash
   npx playwright open [BASE_URL]
   ```

3. **Timing wrong?** Look for non-standard loading patterns (SSR hydration, lazy routes).

4. **Wrong assertion?** Navigate to the final state and check the actual URL/text.

5. **Exploration stale?** Compare the exploration report against the current DOM for each failing step.

**Apply minimal fix:**
- **Stale selector:** Update only the broken line with the correct selector from the live browser
- **Timing:** Add `waitFor` only if Playwright auto-waiting is genuinely insufficient
- **Wrong assertion value:** Update only the assertion with the correct observed value
- **Strict mode violation:** Make selector more specific using `.first()` or a better role/name combination
- **App not running:** Report NEEDS_CONTEXT

After fixing, run the test:
```bash
npx playwright test [TEST_FILE_PATH] --headed --reporter=list
```

If test passes, update test-plan.md:
```markdown
### Status
- [x] Planned
- [x] Explored
- [x] Generated
- [x] Passing
```

## Key Rules
- NEVER rewrite the whole test — minimal fix only
- NEVER add page.waitForTimeout()
- NEVER change passing assertions while fixing failing ones
- If the fix requires re-exploring the scenario from scratch, report BLOCKED

## Output

- Updated test file (minimal changes)
- Updated `docs/playwright-spec-testing/test-plan.md` (if test now passes)

Report when done:
- **Status:** DONE | BLOCKED | NEEDS_CONTEXT
- Root cause identified
- What was changed (file:line)
- Test result after fix: PASS or FAIL (include error if still failing)