Playwright E2e Engineer

---
name: playwright-e2e-engineer
description: MANUAL-ONLY; never auto-invoke. Implement and run Playwright E2E tests for CRITICAL user journeys — resilient user-facing locators (getByRole/getByLabel, testid last), web-first auto-retrying assertions, zero arbitrary sleeps or networkidle waits, project-level auth-state setup, deterministic test data, and trace/screenshot artifacts on failure wired for CI. Each journey names why a cheaper layer was insufficient; E2E stays a small, stable suite, not a UI-tree crawler. Use when asked to write, fix, or harden Playwright tests, automate a login/signup/checkout-style journey in a real browser, or set up Playwright config/fixtures/auth state. WRITES spec files and DRIVES a browser — manual invocation only. Do NOT use for real-boundary tests without a browser (integration-test-designer), isolated component tests (vitest-unit-component-engineer), one-off interactive walkthroughs (clickthrough-test-engineer), or a11y-specific harnesses (accessibility-test-harness).
disable-model-invocation: true
---

# Playwright E2E Engineer

**Reading key:** E2E means end-to-end; UI means user interface; API means
application programming interface; CI means continuous integration; PR means
pull request; CSS means Cascading Style Sheets. This manual-only skill writes
spec files and drives a browser.

## Purpose

Implement the small, stable set of browser tests that prove business-critical
user journeys work end to end: real UI, real backend, deterministic data,
resilient locators, and web-first assertions that wait for the app instead of
sleeping at it. Deliverables are spec files, any config/fixture changes,
failure artifacts wiring, and the real run output.

## Use When

- Use when: asked to write or fix Playwright tests for a user journey
  (signup, login, checkout, core workflow).
- Use when: hardening an existing Playwright suite — flaky waits, brittle
  CSS/XPath selectors, sleep-ridden specs.
- Use when: setting up Playwright config, fixtures, auth-state projects, or
  CI artifacts for the E2E tier.
- Use when: a test plan hands over its E2E items (each with a named reason a
  cheaper layer was insufficient).
- Do NOT use when: the behavior needs no browser — `integration-test-designer`
  (real boundaries) or `vitest-unit-component-engineer` *(manual-only)* (isolated).
- Do NOT use when: the ask is a one-off interactive walkthrough with
  observations — `clickthrough-test-engineer` *(manual-only)*; this skill builds the
  PERMANENT scripted suite.
- Do NOT use when: the ask is keyboard/contrast/screen-reader verification —
  `accessibility-test-harness` (it may inject axe into E2E, but owns that
  design).
- Do NOT use when: diagnosing why an existing test flakes —
  `flaky-test-detective` *(manual-only)* first; this skill implements the proven fix.

## Inputs to Inspect

1. The journeys in scope and their business criticality (from the test plan
   or user) — every journey states why E2E is required.
2. Existing Playwright setup: `playwright.config.*` (projects, baseURL,
   retries, reporters, trace settings), existing fixtures and auth helpers.
3. The app's auth flow and test-account/bootstrap mechanism — how personas
   log in and how storageState can be minted per project setup.
4. Test data reality: how the journey gets deterministic data
   (`test-data-architect` fixtures, API seeding hooks) and how runs are
   isolated from each other.
5. The UI's accessibility surface: are there roles/labels to locate by?
   (Locator quality depends on it; gaps also feed `accessibility-test-harness`.)
6. Installed Playwright version (lockfile) — API and best-practice drift is
   real; compose `docs-first-implementer` *(manual-only)* when uncertain.

## Workflow

1. **Confirm the journey list is small and critical.** Each spec = one
   user-meaningful journey with a named risk. Reject UI-tree crawling —
   route breadth to `clickthrough-test-engineer` *(manual-only)* or component layers.
   If scope needs an owner decision, explain a critical-journey smoke tier
   (few full-browser paths on each PR) versus a broader nightly tier (more
   paths off the PR gate). The smoke tier gives fast deployment evidence but
   misses lower-priority paths; nightly adds coverage at the cost of runner
   minutes, fixture upkeep and later feedback. Use measured or estimated
   runtime and CI pricing where available; mark unknown money/setup/upkeep.
   Recommend critical paths within the PR budget and the remainder nightly,
   explain which named risks justify E2E, then ask one scope/budget question.
   A scope answer does not expand this manual-only invocation or authorize
   new product test hooks.
2. **Set up auth state once per persona:** project-dependency setup that logs
   in via the UI or API and saves `storageState`; tests reuse state, never
   re-login per test. Personas map to `test-data-architect` seeds.
3. **Make each journey data-deterministic:** create the entities the journey
   needs via API/fixture in setup (unique per run/worker), assert on that
   data, clean up structurally. No reliance on ambient shared records.
4. **Write specs with resilient locators:** `getByRole`/`getByLabel`/
   `getByText` (user-facing) first; `data-testid` only where semantics don't
   exist — and flag those as UI semantics gaps. No CSS chains, no XPath.
   Locator ladder in [references/playwright-patterns.md](references/playwright-patterns.md).
5. **Assert web-first, never sleep:** `expect(locator).toBeVisible()/
   toHaveText()` auto-retry; wait for a specific UI outcome or explicit
   response, never `waitForTimeout` and never `networkidle`. Any remaining
   fixed wait is a defect in the spec.
6. **Wire failure evidence:** `trace: on-first-retry` (or on-failure),
   screenshot + video per config policy, artifacts uploaded in CI with run
   id (naming per `screenshot-evidence-planner` conventions when used as
   release evidence).
7. **Run the suite and report honestly:** exact command, per-spec results,
   runtime, retry count (a pass-on-retry is reported as such and routed to
   `flaky-test-detective` *(manual-only)*, not celebrated).
8. **Place in CI** per the automation blueprint: required critical-journey
   smoke runs on the pull request before merge when it is a deployment gate.
   On auto-deploy-on-merge platforms, post-merge smoke is verification of
   the deployed result, never a pre-deploy gate. Run the broader tier nightly;
   budget runtime and shard when needed.

## Output Format

```
PLAYWRIGHT REPORT — <scope>
Journeys: <spec → journey → why E2E was required>
Auth/state setup: <persona → minting path → storageState reuse>
Data strategy: <per-journey deterministic setup + isolation + cleanup>
Locator posture: <role/label coverage; testid fallbacks flagged as semantics gaps>
Specs added/changed: <files, cases>
Commands run: <exact commands>
Results: <real output — pass/fail, runtime, retries (pass-on-retry called out)>
Artifacts: <traces/screenshots/videos + CI upload wiring>
CI placement: <tier, sharding, budget>
Scope choice: <if owner decision needed: smoke vs nightly terms, named risk,
               runtime and money/setup/upkeep, pros/cons, recommendation and why, one question>
Handoffs: <flakes → flaky-test-detective; semantics gaps → accessibility-test-harness;
          non-browser items → integration-test-designer>
```

## Validation Checklist

- [ ] Every spec maps to a named critical journey with an E2E justification.
- [ ] Zero `waitForTimeout` / `networkidle` / manual polling — web-first
      assertions only.
- [ ] Locators are user-facing first; every `data-testid` fallback flagged.
- [ ] Auth via reused storageState from project setup, not per-test login.
- [ ] Test data unique per run/worker; no ambient-record dependence.
- [ ] Failure artifacts (trace at minimum) wired locally and in CI.
- [ ] Suite RUN with real output; pass-on-retry reported and routed.
- [ ] Suite runtime within the tier budget.
- [ ] An owner-facing journey-scope choice explains the runtime and upkeep
      tradeoff and recommends a tier for each risk before asking.

## Gotchas

- `networkidle` is explicitly discouraged and lies on apps with polling/
  websockets — wait for the UI outcome instead.
- Free-text `getByText` on dynamic content (dates, counts) flakes; anchor on
  stable accessible names or pass exact expected data you seeded.
- Reused storageState goes stale when auth/session format changes — mint in
  a setup project per run, don't commit long-lived state files.
- Parallel workers sharing one seeded account trip over each other's data —
  worker-scoped uniqueness is mandatory, not optional.
- Auto-retrying assertions can mask slow regressions — keep default timeouts
  honest; a journey that needs 60s timeouts has a product problem to report.
- Strict-mode locator violations (multiple matches) are design feedback:
  disambiguate by role/name, don't `.first()` your way past them.

## Stop Conditions

- No runnable environment (app won't start, no test accounts/bootstrap) →
  report the blocker; do not write specs that have never executed and call
  them a suite.
- The journey list balloons past the tier's runtime budget → stop and
  re-negotiate scope with the plan/strategy owner instead of shipping a slow
  suite.
- Required test hooks (API seeding, test-only routes) don't exist and would
  require product changes → surface as a separate classified change.
- A journey fails against the real app (product bug, not spec bug) → report
  the failure with trace; the fix is `systematic-debugger` *(manual-only)*/product work, not
  spec weakening.

## Supporting Files

- [references/playwright-patterns.md](references/playwright-patterns.md) —
  locator ladder, web-first assertion catalog, auth-state project setup
  recipe, sharding/CI wiring.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination within the test-level cluster
  and against `clickthrough-test-engineer`.