| name | e2e |
| description | Run e2e tests, fix flake and outdated tests, identify bugs against spec. Use when running e2e tests, debugging test failures, or fixing flaky tests. Never changes source code logic or API without spec backing. |
E2E Testing
Principles (Always Active)
These apply whenever working with e2e tests, test failures, or test flakiness:
Failure Taxonomy
Every e2e failure is exactly one of:
A. Flaky (test infrastructure issue)
- Race conditions, timing-dependent assertions
- Stale selectors after UI changes
- Missing waits, incorrect wait targets
- Network timing, mock setup ordering
- Symptom: passes on retry, fails intermittently
B. Outdated (test no longer matches implementation)
- Test asserts old behavior that was intentionally changed
- Selectors reference removed/renamed elements
- API contract changed, test wasn't updated
- Symptom: consistent failure, app works correctly
C. Bug (implementation doesn't match spec)
- Test correctly asserts spec'd behavior, code is wrong
- Only classify as bug when a spec exists to validate against
- If no spec exists, classify as "unverified failure" and report to the user
Fix Rules by Category
Flaky fixes:
- Replace
waitForTimeout with auto-waiting locators
- Replace brittle CSS selectors with
getByRole/getByLabel/getByTestId
- Fix race conditions with
expect() web-first assertions
- Fix mock/route setup ordering (before navigation)
- Never add arbitrary delays - fix the underlying wait
