dev-e2e-testing

name	dev-e2e-testing
description	Write and maintain Playwright end-to-end tests that drive the whole system through its real UI/API — setup, fixtures, test independence, flake handling, CI wiring. Trigger on "write e2e tests", "set up Playwright", "test the full user flow", "our e2e tests are flaky", or when tests/e2e needs work.
argument-hint	[lite|full|ultra]

End-to-End Testing

E2E tests are the slowest, most realistic, and most expensive tests in the pyramid — they earn their keep only by covering what integration tests structurally can't: the assembled system behaving correctly through its real UI or public API. Write few, make them count, keep them from rotting into a flaky tax on every PR.

Delivery Mode (lite | full | ultra, default lite)

Mode is the trailing argument when it is exactly lite, full, or ultra; everything else is the task/feature description. No mode given → lite.

• lite (default) — the one critical happy-path flow for the feature, one test.
• full — happy path + the realistic failure/edge flows (invalid input, permission denied, empty state) worth the E2E cost.
• ultra — full's coverage run across environments/browsers/viewports in parallel (subagent type dev-tester when available, else general-purpose, one per target), merged and reported together.

1. Decide What Earns an E2E Test

Not every path deserves one — E2E tests are slow and worth writing only for what genuinely needs the real system:

• A user-facing flow spanning multiple pages/screens or a full request lifecycle (signup → verify → first action) — the kind of bug that only shows up when the pieces are wired together for real.
• A critical business path (checkout, payment, auth) where a regression is expensive enough to justify the cost.
• Skip it for anything a unit or integration test already proves — an E2E test re-verifying validation logic already covered lower in the pyramid is redundant cost with no new signal.

2. Location and Structure

Tests live under tests/e2e/ (or tests/ if the project has no unit/integration split yet) — never inside src/ or colocated with implementation. Name by user-facing flow, not by page: checkout-with-saved-card.spec.ts, not cart-page.spec.ts.

3. Tooling

Playwright. Run headless in CI, headed locally for debugging.

Config, a fixture-backed test, and a page-object example are in references/details.md.

4. Independence and Fixtures

• Each test creates its own data. A test that depends on another test's leftover state (a specific user, a specific record) breaks the moment tests run in a different order or in parallel — seed what the test needs in its own setup.
• Isolate the environment. A dedicated test/staging environment or ephemeral per-run environment, never against production — an E2E test that mutates real user data is a production incident waiting to happen, not a test.
• Clean up after, but design for survivable failure. A test that crashes mid-run shouldn't leave orphaned data poisoning the next run — prefer generating uniquely-namespaced data (timestamped/UUID'd) over relying on teardown always executing.

5. Flake Is a Bug, Not Weather

A flaky E2E test that gets re-run until green trains everyone to ignore red — treat flake as seriously as a functional bug:

• Wait for state, never for time. waitFor(selector/condition), not sleep(2000) — a fixed sleep is either too short (still flaky) or too long (slow for no reason). Playwright's built-in auto-waiting already handles most of this; a manual sleep added on top is almost always working around a different, unfixed race.
• Assert on the outcome the user would see, not an implementation-adjacent side effect (a specific network call count, an internal state variable) — the E2E layer's whole value is verifying what's actually visible.
• A test that fails intermittently gets root-caused, not retried into passing. A retry-until-green config hides real races; use retries only as a last-resort CI stabilizer for a known, understood source of nondeterminism (e.g. a third-party sandbox's occasional slowness), never as the fix for an unexplained flake.
• Quarantine, don't delete, a test that's flaky for an unknown reason — mark it skipped with a tracking note, keep the coverage gap visible, don't silently lose the signal.

A flake-troubleshooting checklist is in references/details.md.

6. CI Wiring

E2E suites are usually the slowest CI stage — run them on a separate job/stage from unit+integration so a slow E2E run doesn't block fast feedback, and shard across workers when the suite is large enough to benefit (sharding example in references/details.md). See the github-actions skill for the workflow/matrix setup itself.

7. Verify Before Handing Back

Run the new test and confirm it fails against a broken version of the flow (comment out the fix, or run against main before the feature) as well as passing against the real one — an E2E test that never fails might be testing nothing.