rsc-universal 0.1.1

package/skills/e2e-testing/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: e2e-testing
+description: "Use when writing or stabilizing browser end-to-end tests with Playwright — driving real navigation, forms, logins, and multi-step user journeys through an actual browser, picking durable locators, or killing tests that pass locally but flake in CI. Covers getByRole/getByTestId locator choice, web-first assertions, storageState auth via setup projects, retries/trace config, sharding, and the 2026 flakiness playbook. Triggers: 'write a Playwright test', 'my e2e tests flake in CI but pass locally', 'set up storageState so I don't log in every test', 'getByRole vs CSS selector', 'shard Playwright across machines', 'trace on retry', 'strict mode resolved to 2 elements', 'els tests d'extrem a extrem fallen aleatòriament al pipeline', 'los tests e2e fallan a veces'. NOT in-process component/unit web tests (that is testing-web), NOT pytest suites (that is testing-py), NOT a11y audits as the goal (that is accessibility), NOT building the CI pipeline itself (that is github-actions)."
+tags: [playwright, e2e, browser-testing, flakiness, ci]
+recommends: [testing-web, accessibility, performance, github-actions, debug]
+origin: risco
+---
+
+# e2e-testing — drive a real browser, keep it deterministic
+
+You write **Playwright** tests that walk a real browser through real user journeys — log in, fill a
+form, check out, navigate across pages — and you keep those tests deterministic enough to gate a
+merge. The whole game is one tension: e2e tests catch integration bugs nothing else can, and they
+are the slowest, flakiest layer you own. Every rule below exists to buy back determinism.
+
+Pin `@playwright/test` and provision browsers with `npx playwright install --with-deps`. Current
+line is **Playwright v1.60.x** (v1.60.0 shipped 2026-05-11). The `_react` / `_vue` selector engines
+and the `:light` Shadow-DOM suffix were **removed in v1.58.0** — at any version you should be pinning
+they are long gone, so do not reach for them.
+
+## What good looks like
+
+- **User-facing locators.** Tests find elements the way a user does — by role and accessible name —
+  not by `div.card > button:nth-child(2)`. The test survives a refactor that the user never sees.
+- **Web-first assertions.** Every assertion auto-retries until the DOM settles. You never read a
+  value once and compare it.
+- **Deterministic by design.** No `waitForTimeout`. No test that depends on another test's leftovers.
+  Flakiness is a design defect you prevent, not a rerun you tolerate.
+- **Traces on retry.** CI captures a full trace the first time a test retries, so a CI-only failure
+  is debuggable from the artifact without a local repro.
+
+## Is this even an e2e test?
+
+E2e is the most expensive layer. Spend it only on journeys that cross pages or services. Route the rest out.
+
+| The goal is… | Layer | Why |
+|---|---|---|
+| A multi-step journey across pages/auth/services in a real browser | **e2e (here)** | Only a real browser proves the pieces integrate. |
+| One component or pure function, rendered in-process (Vitest/Jest, Testing Library) | `../testing-web/SKILL.md` | A browser round-trip to test render logic is slow and flaky for no gain. |
+| "Is this page accessible?" — WCAG/ARIA as the deliverable | `../accessibility/SKILL.md` | E2e may *call* axe inside a test, but auditing a11y is its own skill. |
+| "Is this page fast?" — LCP/CWV budgets | `../performance/SKILL.md` | Perf budgets are a different signal than journey correctness. |
+| The runner matrix, caching, the pipeline itself | `../github-actions/SKILL.md` | E2e contributes a *job*; owning the pipeline is theirs. |
+
+Rule: if you can prove it without launching a browser, you should. Push logic down to `testing-web`.
+
+## Locators: the priority ladder
+
+Pick the highest rung that uniquely identifies the element. Higher rungs track what the user
+perceives, so they survive markup churn.
+
+1. `getByRole('button', { name: 'Buy' })` — role + accessible name. Default choice; doubles as an a11y signal.
+2. `getByLabel('Email')` / `getByPlaceholder(...)` — form fields.
+3. `getByText('Order confirmed')` — visible copy that uniquely identifies content.
+4. `getByTestId('cart-total')` — when nothing user-facing is stable; requires a deliberate `data-testid`.
+5. CSS as a last resort, scoped and shallow.
+
+Never XPath, never `nth-child` chains, never the removed `_react`/`_vue`/`:light` engines.
+
+```ts
+// Bad — couples the test to DOM structure; one wrapper div breaks it.
+await page.locator('div.card > button:nth-child(2)').click();
+
+// Good — finds the button the way the user reads it.
+await page.getByRole('button', { name: 'Buy' }).click();
+```
+
+**Strict mode.** A locator that matches two nodes *throws* — that is the framework catching an
+ambiguous selector for you. Tighten the locator (`getByRole(...).and(...)`, scope with
+`page.getByRole('listitem').filter({ hasText: 'Pro' })`). Reaching for `.first()` to silence the
+error hides the ambiguity and is the next flake.
+
+## Assertions: web-first only
+
+```ts
+// Bad — reads the DOM once, before the async update lands; races the render.
+expect(await page.locator('#status').textContent()).toBe('Submitted');
+
+// Good — re-polls the element until it says 'Submitted' or the timeout fires.
+await expect(page.getByTestId('status')).toHaveText('Submitted');
+```
+
+`expect(locator)` assertions (`toBeVisible`, `toHaveText`, `toHaveURL`, `toHaveCount`) retry until
+the condition holds. A read-once value (`await locator.textContent()` then compare) captures a single
+frame and loses every race against a re-render. If you find `expect(await` in a test, it is a bug.
+
+## Auto-wait and the no-sleep rule
+
+Locator actions (`click`, `fill`, `check`) already auto-wait: they block until the element is
+visible, stable, enabled, and receiving events. So `waitForTimeout(2000)` is never the right wait —
+it is either too short (flake) or too long (slow), and it waits for wall-clock time instead of the
+thing you actually care about.
+
+| Instead of guessing with a sleep | Wait on the real signal |
+|---|---|
+| "give the button time to appear" | `await expect(locator).toBeVisible()` |
+| "wait for navigation" | `await page.waitForURL('**/checkout')` |
+| "wait for the XHR/fetch" | `const r = page.waitForResponse('**/api/order'); …action…; await r;` |
+| "wait for the list to fill" | `await expect(page.getByRole('row')).toHaveCount(5)` |
+
+The ordering trap: subscribe to a response (or register a `page.route` mock) **before** the action
+that triggers it, or you miss the event.
+
+```ts
+// Bad — handler registered after goto; the initial request already fired unmocked.
+await page.goto('/orders');
+await page.route('**/api/orders', route => route.fulfill({ json: [] }));
+
+// Good — mock in place before navigation, so the first request is intercepted.
+await page.route('**/api/orders', route => route.fulfill({ json: [] }));
+await page.goto('/orders');
+```
+
+## Fixtures and page objects
+
+Fixtures give every test a fresh, isolated setup and kill copy-pasted boilerplate. Extend the base
+`test` with your own; the code before `use(value)` is setup, after it is teardown.
+
+```ts
+import { test as base } from '@playwright/test';
+import { CheckoutPage } from './pages/checkout';
+
+type Fixtures = { checkout: CheckoutPage };
+
+export const test = base.extend<Fixtures>({
+  checkout: async ({ page }, use) => {
+    const checkout = new CheckoutPage(page); // setup: depends on the built-in `page`
+    await use(checkout);                      // hand it to the test
+    // teardown after the test goes here, if any
+  },
+});
+```
+
+Option fixtures (`['default', { option: true }]`) let a project or `test.use()` flip behavior
+without new fixtures. Keep page objects thin — locators and intent-named actions
+(`checkout.placeOrder()`), no assertions buried inside them. Full page-object recipe lives in
+[references/config-and-ci.md](references/config-and-ci.md).
+
+## Auth and storageState
+
+Logging in through the UI on every test is slow and a flake surface. Log in **once** in a `setup`
+project, save the authenticated session to JSON, and load it via `storageState` in the projects that
+depend on it.
+
+- A `setup` project runs the login spec and writes `playwright/.auth/<role>.json`.
+- Real test projects declare `dependencies: ['setup']` and `use: { storageState: '…/<role>.json' }`.
+- **One file per role** (admin, member, anon) — never share one mutated session across roles.
+- **Regenerate every CI run; gitignore the `.auth/` dir.** Committed session state leaks secrets and
+  goes stale.
+
+The full multi-role setup-project wiring is in [references/config-and-ci.md](references/config-and-ci.md).
+
+## playwright.config.ts (condensed)
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,        // a stray test.only fails CI instead of skipping the suite
+  retries: process.env.CI ? 2 : 0,     // retry only in CI; locally a flake should hurt
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? [['github'], ['html']] : 'list',
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',           // full trace captured the first time a test retries
+  },
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'] },
+    { name: 'webkit',   use: { ...devices['Desktop Safari'] }, dependencies: ['setup'] },
+  ],
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+Open a captured trace with `npx playwright show-trace`. The full annotated config (per-role
+storageState, firefox, blob reporter for sharding) is in
+[references/config-and-ci.md](references/config-and-ci.md).
+
+## CI (GitHub Actions)
+
+The shape: install browsers with OS deps, run, shard when one box can't finish inside the ~5–10 min
+budget, upload the trace and HTML report as artifacts.
+
+```yaml
+- run: npx playwright install --with-deps
+- run: npx playwright test --shard=${{ matrix.shard }}/4
+- uses: actions/upload-artifact@v4
+  if: ${{ !cancelled() }}
+  with: { name: report-${{ matrix.shard }}, path: playwright-report/, retention-days: 7 }
+```
+
+Scale: bump `workers` to use a single machine; add `--shard=i/N` across machines only once a single
+box overruns the budget. Sharded runs emit blob reports you merge with `npx playwright merge-reports`.
+Full workflow (matrix, blob report, merge job) is in [references/config-and-ci.md](references/config-and-ci.md).
+
+## Flakiness playbook
+
+A 3% flake rate on a 40-minute pipeline burns roughly an engineer-day a week on reruns, so treat
+flakes as bugs with named causes. **Open the trace first** (`show-trace`) — it replays the exact
+failing run with DOM, network, and console; guessing from a one-line CI log is how flakes survive.
+
+| Symptom in CI | Cause | Fix |
+|---|---|---|
+| Assertion races a re-render | Read-once value, not web-first | `await expect(locator).toHaveText(...)` |
+| Mock/intercept never fires | `page.route` registered after `goto` | Register the route before the navigation |
+| Test hangs / times out in an SPA | `networkidle` never settles (polling, websockets) | Wait on a locator/URL, not `networkidle` |
+| `waitForResponse` misses the call | Subscribed after the action fired | `const r = page.waitForResponse(...)` before the action |
+| "strict mode: resolved to 2 elements" | Ambiguous locator | Tighten with role+name/`filter`, not `.first()` |
+| Passes alone, fails in the suite | `storageState` leak / shared mutable state | Per-role state file; fresh context per test |
+| Wrong fixture/state in one file | `test.use()` scope confusion | Scope `test.use` to the right describe block |
+| Green headed, red headless (or vice-versa) | Viewport/animation/timing drift | Pin viewport; reduce motion; debug in the failing mode |
+
+Per-pattern reproduction and corrected code is in [references/flakiness-playbook.md](references/flakiness-playbook.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `await page.waitForTimeout(2000)` | Couples the test to wall-clock; too short flakes, too long drags | Wait on locator/URL/response |
+| XPath or `:nth-child` locators | Breaks on any markup refactor the user never sees | `getByRole`/`getByTestId` ladder |
+| `page.$(...)` / `page.$$(...)` element handles | No auto-wait, no retry — pre-locator API | `page.locator(...)` / `getBy*` |
+| `expect(await locator.textContent()).toBe(...)` | Reads one frame; races the async update | `await expect(locator).toHaveText(...)` |
+| Committing `storageState` JSON | Leaks session secrets, goes stale, false green | Gitignore `.auth/`; regenerate per run |
+| `trace: 'on'` always | Heavy artifacts, slows every run | `trace: 'on-first-retry'` |
+| Tests that depend on run order | One reorder cascades failures | Each test self-contained; fresh context |
+| Driving pure logic through the browser | Slow + flaky for a unit-level check | Push it to `../testing-web/SKILL.md` |
+| `.first()` to silence strict mode | Hides ambiguity → the next flake | Make the locator unique |
+
+When a flake resists the table, hand the trace to `../debug/SKILL.md` — reproduce as a rate (k/N
+runs), isolate one variable, fix the cause, not the symptom.
+
+## Verify
+
+Run `scripts/verify.sh [dir]` over the test/config files you emit. It is a read-only static lint
+(no browser, no network) that fails on the skill's own banlist: `waitForTimeout(`, XPath/`//`
+locators, `page.$(`/`page.$$(` handles, `expect(await` read-once assertions, and any
+`playwright.config.*` missing both `trace` and `retries`. Clean or empty target exits 0.

package/skills/e2e-testing/evals/README.md

@@ -0,0 +1,10 @@
+# e2e-testing evals
+
+`cases.yaml` holds three groups scored by an LLM judge, not a runtime test of Playwright itself.
+`should_trigger` lists prompts where the skill must load (each with a `why`, including the non-obvious
+flakiness and strict-mode cases and a Catalan phrasing); `should_not_trigger` lists near-misses that
+must route to a real sibling (`route_to`) instead of loading here; `capability` is one end-to-end
+scenario with a `must_include` rubric that the judge grades a skill-guided answer against. Run them
+through the repo's eval harness, which loads the skill, replays each prompt, and checks routing plus
+rubric coverage. Nothing here launches a browser or runs Playwright — that lives in the produced test
+suite, which `scripts/verify.sh` statically lints.

package/skills/e2e-testing/evals/cases.yaml

@@ -0,0 +1,64 @@
+skill: e2e-testing
+
+# Prompts that MUST load e2e-testing. This skill owns driving a real browser
+# through user journeys with Playwright and keeping those tests deterministic:
+# durable locators, web-first assertions, storageState auth, retries/trace, and
+# the flakiness playbook. Flakiness is the non-obvious core — half the reason
+# e2e exists as a discipline is that the tests rot into reruns otherwise.
+should_trigger:
+  - prompt: "Write a Playwright test for the login then checkout flow."
+    why: "A multi-step journey across auth and pages in a real browser is the canonical e2e case; the skill drives the locator/assertion/auth choices."
+
+  - prompt: "My e2e tests pass locally but flake on CI — how do I make them deterministic?"
+    why: "Non-obvious core: flakiness is the central failure mode of e2e, and the skill carries the named-pattern playbook (route-after-goto, networkidle, read-once, storageState leak)."
+
+  - prompt: "How do I set up storageState so I don't log in through the UI on every test?"
+    why: "Auth via a setup project that writes session JSON and dependent projects loading it is exactly the storageState recipe this skill owns."
+
+  - prompt: "Should I use getByRole or a CSS selector for this submit button?"
+    why: "Locator strategy — the role>label/text>testId>CSS ladder and the v1.58.0 removal of _react/_vue — is core e2e judgment."
+
+  - prompt: "Els tests d'extrem a extrem fallen aleatòriament al pipeline, com els estabilitzo?"
+    why: "Catalan for 'the end-to-end tests fail randomly in the pipeline' — flaky CI e2e, the skill's central concern."
+
+  - prompt: "How do I shard my Playwright suite across CI machines and merge the reports?"
+    why: "Scale-out via --shard with blob reports merged by merge-reports is the CI section of this skill."
+
+  - prompt: "Strict mode says my locator resolved to 2 elements — how do I fix it the right way?"
+    why: "Non-obvious: the fix is tightening the locator, not .first(); recognizing strict mode as a caught ambiguity is e2e locator discipline."
+
+# NEAR-MISS prompts that must NOT load e2e-testing. Each routes to a sibling that
+# exists in the catalog. The trap: not every test or browser-shaped task is a
+# real-browser user journey kept deterministic.
+should_not_trigger:
+  - prompt: "Write a Vitest component test for my Button component."
+    route_to: testing-web
+    why: "An in-process component/unit test rendered without a real browser round-trip belongs to testing-web; driving a browser here would be slow and pointless."
+
+  - prompt: "Add pytest tests for my FastAPI orders service."
+    route_to: testing-py
+    why: "Python backend unit/integration testing is testing-py; there is no browser journey to drive."
+
+  - prompt: "Audit this page for WCAG accessibility violations and fix the ARIA issues."
+    route_to: accessibility
+    why: "When the deliverable is the a11y audit itself, it is accessibility; e2e may call axe inside a test but auditing is not its job."
+
+  - prompt: "Set up the GitHub Actions runner matrix and dependency caching for the whole repo."
+    route_to: github-actions
+    why: "Owning the pipeline — runners, caching, matrices — is github-actions; e2e only contributes a test job."
+
+# One end-to-end scenario graded WITH vs WITHOUT the skill. A skill-guided answer
+# builds for determinism from the start (user-facing locators, web-first
+# assertions, storageState setup project, trace-on-retry, no sleeps); an
+# ungrounded answer reaches for CSS/XPath, read-once asserts, waitForTimeout,
+# and reruns to mask the flake.
+capability:
+  - scenario: "An authenticated checkout e2e suite flakes intermittently in CI but passes locally. Stabilize it: write a representative test, the playwright.config.ts, the auth setup, and the CI job."
+    must_include:
+      - "User-facing locators (getByRole/getByLabel/getByTestId) for the journey; no XPath, no :nth-child chains, no removed _react/_vue/:light engines."
+      - "Web-first assertions (await expect(locator).toHaveText/toBeVisible/toHaveURL) — never expect(await locator.textContent())."
+      - "Auth via a setup project writing session JSON, dependent projects loading it with storageState and dependencies:['setup'], one file per role, .auth/ gitignored and regenerated per CI run."
+      - "playwright.config.ts with retries: process.env.CI ? 2 : 0 and use:{ trace: 'on-first-retry' }, baseURL, and a projects array including the setup project."
+      - "No waitForTimeout anywhere; waits on locator assertions, waitForURL, or waitForResponse subscribed BEFORE the action, and route mocks registered before goto."
+      - "CI job runs npx playwright install --with-deps, runs the suite (optionally --shard with blob report + merge-reports), and uploads trace + HTML report as artifacts."
+      - "Treats the flake as a cause to diagnose (open the trace first, measure as a rate) rather than papering over it with retries or sleeps."

package/skills/e2e-testing/references/config-and-ci.md

@@ -0,0 +1,156 @@
+# config-and-ci — full Playwright config, multi-role auth, and the CI workflow
+
+Everything the SKILL condenses. Current line is Playwright v1.60.x; install browsers with
+`npx playwright install --with-deps`.
+
+## Full annotated playwright.config.ts
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  outputDir: './test-results',
+  fullyParallel: true,                 // run files in parallel, tests within a file in parallel
+  forbidOnly: !!process.env.CI,        // a stray test.only fails CI rather than silently skipping the rest
+  retries: process.env.CI ? 2 : 0,     // CI absorbs infra blips; locally a flake should fail loud
+  workers: process.env.CI ? 1 : undefined, // 1 worker/shard in CI when sharding; uncapped locally
+  timeout: 30_000,                     // per-test cap
+  expect: { timeout: 5_000 },          // per web-first-assertion poll cap
+
+  reporter: process.env.CI
+    ? [['blob'], ['github']]           // blob = mergeable across shards; github = inline annotations
+    : [['html', { open: 'never' }], ['list']],
+
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',           // full DOM/network/console trace the first time a test retries
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+
+  projects: [
+    // 1. Auth setup projects — one per role. They run first and write session JSON.
+    { name: 'setup-admin',  testMatch: /admin\.setup\.ts/ },
+    { name: 'setup-member', testMatch: /member\.setup\.ts/ },
+
+    // 2. Real test projects load the right storageState and depend on their setup.
+    {
+      name: 'chromium-admin',
+      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/admin.json' },
+      dependencies: ['setup-admin'],
+      testMatch: /.*admin.*\.spec\.ts/,
+    },
+    {
+      name: 'chromium-member',
+      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/member.json' },
+      dependencies: ['setup-member'],
+      testMatch: /.*member.*\.spec\.ts/,
+    },
+    {
+      name: 'webkit-member',
+      use: { ...devices['Desktop Safari'], storageState: 'playwright/.auth/member.json' },
+      dependencies: ['setup-member'],
+      testMatch: /.*member.*\.spec\.ts/,
+    },
+  ],
+
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI, // reuse the dev server locally; always fresh in CI
+    timeout: 120_000,
+  },
+});
+```
+
+## Multi-role storageState setup project
+
+One spec per role. Each logs in once and saves the session; the dependent projects above load it.
+
+```ts
+// e2e/auth/member.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const memberFile = 'playwright/.auth/member.json';
+
+setup('authenticate as member', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.MEMBER_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.MEMBER_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // Wait on a real post-login signal before saving, or you save a half-authenticated state.
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+
+  await page.context().storageState({ path: memberFile });
+});
+```
+
+Duplicate for `admin.setup.ts` with admin credentials and `playwright/.auth/admin.json`.
+
+Always gitignore the auth dir — committed sessions leak secrets and go stale:
+
+```gitignore
+playwright/.auth/
+test-results/
+playwright-report/
+blob-report/
+```
+
+Faster path when you have a programmatic login: skip the UI entirely and seed `storageState` from an
+API token or a `request` call inside the setup project — same output JSON, no browser round-trip.
+
+## GitHub Actions workflow (shard + merge + artifacts)
+
+```yaml
+name: e2e
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npx playwright install --with-deps      # browsers + OS libs
+      - run: npx playwright test --shard=${{ matrix.shard }}/4
+        env:
+          CI: 'true'
+          BASE_URL: http://localhost:3000
+          MEMBER_EMAIL: ${{ secrets.MEMBER_EMAIL }}
+          MEMBER_PASSWORD: ${{ secrets.MEMBER_PASSWORD }}
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}                       # keep the trace even when the job fails
+        with:
+          name: blob-report-${{ matrix.shard }}
+          path: blob-report/
+          retention-days: 7
+
+  merge-report:
+    if: ${{ !cancelled() }}
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with: { path: all-blob-reports, pattern: blob-report-*, merge-multiple: true }
+      - run: npx playwright merge-reports --reporter=html ./all-blob-reports
+      - uses: actions/upload-artifact@v4
+        with: { name: html-report, path: playwright-report/, retention-days: 14 }
+```
+
+Sharding only earns its complexity once a single runner overruns the ~5–10 min budget. Below that,
+raise `workers` on one machine first. Each shard emits a `blob` report; the merge job stitches them
+into one HTML report so reviewers see the whole suite, not four fragments.
+
+Download `html-report`, run `npx playwright show-report`, and open any failed test's trace inline.

package/skills/e2e-testing/references/flakiness-playbook.md

@@ -0,0 +1,124 @@
+# flakiness-playbook — the 2026 patterns, reproduced and fixed
+
+A flaky test passes and fails on the same code. Industry flaky rates sit around 2–5%; a 3% rate on a
+40-minute pipeline costs roughly an engineer-day per week in reruns and erodes trust until people
+"just hit retry". Each pattern below has a named cause and a deterministic fix. **Open the trace
+first** — `npx playwright show-trace trace.zip` replays the failing run with DOM snapshots, network,
+and console, which turns a one-line CI log into an actual diagnosis.
+
+## 1. Auto-wait racing a re-render (read-once assertion)
+
+The element exists when you read it, but the async update lands a frame later.
+
+```ts
+// Repro — captures one frame; flakes when the fetch resolves after the read.
+const total = await page.locator('#total').textContent();
+expect(total).toBe('$42.00');
+
+// Fix — web-first assertion re-polls until the text matches or times out.
+await expect(page.getByTestId('total')).toHaveText('$42.00');
+```
+
+## 2. Route handler registered after `goto`
+
+The first request fires before the mock is in place, so it hits the network unmocked.
+
+```ts
+// Repro — initial /api/orders already went out by the time the route is set.
+await page.goto('/orders');
+await page.route('**/api/orders', r => r.fulfill({ json: orders }));
+
+// Fix — register before navigation; now the first request is intercepted.
+await page.route('**/api/orders', r => r.fulfill({ json: orders }));
+await page.goto('/orders');
+```
+
+## 3. `networkidle` never settling in an SPA
+
+SPAs with polling, websockets, or analytics beacons keep the network busy forever, so
+`waitUntil: 'networkidle'` hangs until timeout.
+
+```ts
+// Repro — hangs because a heartbeat poll keeps the connection alive.
+await page.goto('/dashboard', { waitUntil: 'networkidle' });
+
+// Fix — wait on a concrete UI signal instead of network silence.
+await page.goto('/dashboard');
+await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+```
+
+## 4. `waitForResponse` subscribed too late
+
+If you `await` the action and only then wait for the response, the event already fired.
+
+```ts
+// Repro — the click's response can resolve before the listener attaches.
+await page.getByRole('button', { name: 'Save' }).click();
+const res = await page.waitForResponse('**/api/save'); // may hang or catch the wrong call
+
+// Fix — start waiting first, then act, then await the promise.
+const resPromise = page.waitForResponse('**/api/save');
+await page.getByRole('button', { name: 'Save' }).click();
+const res = await resPromise;
+expect(res.ok()).toBeTruthy();
+```
+
+## 5. Strict-mode violation ("resolved to 2 elements")
+
+A locator matches more than one node. The throw is correct — your selector is ambiguous.
+
+```ts
+// Repro — two "Delete" buttons on the page.
+await page.getByRole('button', { name: 'Delete' }).click(); // throws in strict mode
+
+// Fix — scope to the row, do not paper over it with .first().
+await page
+  .getByRole('row', { name: 'Invoice 1024' })
+  .getByRole('button', { name: 'Delete' })
+  .click();
+```
+
+## 6. `storageState` leakage between tests/roles
+
+Sharing one mutated session file across roles, or letting one test's writes bleed into the next.
+
+- One state file per role: `admin.json`, `member.json`, `anon` (none).
+- Regenerate every CI run; gitignore `playwright/.auth/`.
+- Playwright already gives each test a fresh `BrowserContext` (cookies/storage reset). If state leaks
+  between tests, the cause is a shared fixture or committed state — not the framework.
+
+## 7. `test.use()` scope confusion
+
+`test.use({...})` applies to its whole file or `describe` block. Setting it at the top when only one
+test needs the override silently changes siblings.
+
+```ts
+test.describe('mobile checkout', () => {
+  test.use({ viewport: { width: 390, height: 844 } }); // scoped to this block only
+  test('completes on a phone viewport', async ({ page }) => { /* ... */ });
+});
+```
+
+## 8. Headed-vs-headless drift
+
+Green when watched, red in CI (or vice-versa). Usually viewport size, animation timing, or font
+rendering differences.
+
+- Pin `viewport` in the config so headed and headless agree.
+- Disable animations for determinism: `use: { ...devices['Desktop Chrome'] }` plus a global
+  `* { animation: none !important; transition: none !important; }` style, or
+  `await page.emulateMedia({ reducedMotion: 'reduce' })`.
+- Reproduce in the mode that fails: run CI's exact command headless locally, or
+  `npx playwright test --headed --project=chromium` to watch a headed-only failure.
+
+## Trace-viewer workflow
+
+1. CI uploads the trace (config has `trace: 'on-first-retry'`).
+2. Download the artifact, then `npx playwright show-trace path/to/trace.zip`.
+3. Step the timeline: inspect the DOM snapshot at the failing action, the network tab for the
+   missed/late request, and the console for errors.
+4. Reproduce locally with `--repeat-each=20` (or `--shard` parity) to measure the flake as a rate.
+5. Fix the cause from the table above; confirm the rate hits zero, not merely lower.
+
+When a flake survives this, hand the trace to `../debug/SKILL.md`: turn it into a measured k/N rate,
+isolate one variable at a time, fix the cause, and add the test that proves it gone.