Claude Skill

playwright-ops

Playwright end-to-end testing operations - selectors, fixtures, network mocking, auth, parallelism, CI, visual regression, flake hunting. Use for: playwright, e2e test, end-to-end testing, browser test, getByRole, page object, storageState, trace viewer, flaky test, test sharding

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_playwright-ops-6aef525.zip · 24 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/playwright-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Playwright Operations

End-to-end testing with Playwright Test (@playwright/test, TS/JS). A Python flavor (pytest-playwright) exists with the same browser API but pytest-style fixtures — patterns here translate directly; runner config does not.

Quick Start

npm init playwright@latest          # scaffold config + example test + GH Actions workflow
npx playwright test                 # run all tests, all projects
npx playwright test --project=chromium --grep "@smoke"
npx playwright test --ui            # interactive UI mode (watch, time-travel)
npx playwright codegen https://app.local   # record actions -> generated locators
npx playwright show-report          # open last HTML report
npx playwright show-trace trace.zip # inspect a trace

Selector Strategy

Hierarchy — always prefer the highest tier that uniquely matches:

Tier Locator When
1 page.getByRole('button', { name: 'Submit' }) Anything with an ARIA role — buttons, links, headings, textboxes. Tests a11y for free
2 page.getByLabel('Password') Form fields with labels
3 page.getByPlaceholder('name@example.com') Inputs without labels (fix the label instead, when you can)
4 page.getByText('Welcome back') Non-interactive text content
5 page.getByTestId('cart-total') Stable hook when semantics don't disambiguate. Configure attribute via testIdAttribute
6 page.locator('css=...') / xpath= Last resort. Coupled to DOM structure; breaks on refactor

Why: tiers 1–4 locate the way a user perceives the page — resilient to markup changes, and getByRole fails loudly when accessibility regresses. CSS/XPath encode implementation detail.

Narrowing without CSS:

page.getByRole('listitem')
    .filter({ hasText: 'Product 2' })
    .getByRole('button', { name: 'Add to cart' });

page.getByRole('row').filter({ has: page.getByRole('cell', { name: 'Alice' }) });

Web-First Assertions (no manual waits, ever)

// BAD — checks once, races the render; sleeps are flake factories
expect(await page.getByText('welcome').isVisible()).toBe(true);
await page.waitForTimeout(2000);

// GOOD — auto-retries until pass or timeout
await expect(page.getByText('welcome')).toBeVisible();
await expect(page.getByRole('list')).toHaveCount(3);
await expect(page).toHaveURL(/\/dashboard/);
await expect.soft(page.getByTestId('status')).toHaveText('Active'); // don't stop test on failure

Actions (click, fill) auto-wait for actionability (visible, stable, enabled). If you feel the need for waitForTimeout, you're missing an assertion or an await expect(...) on a state change. For async non-DOM conditions use expect.poll(() => fn()) or expect(async () => {...}).toPass().

Lint guard: enable @typescript-eslint/no-floating-promises — a missing await on an assertion is the most common silent-pass bug.

Config Skeleton

Full production template with comments: assets/playwright.config.template.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? 'blob' : 'html',
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    testIdAttribute: 'data-testid',
  },
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
      dependencies: ['setup'],
    },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Fixtures Decision Tree

What do I need to share/setup?
│
├─ Per-test object (page object, seeded record)
│  └─ test.extend() test-scoped fixture — setup, await use(x), teardown
│
├─ Expensive, safe-to-share resource (DB pool, test account)
│  └─ Worker-scoped: [fn, { scope: 'worker' }] — once per worker process
│
├─ Side effect every test needs (log capture, network stub)
│  └─ Automatic: [fn, { auto: true }] — runs without being referenced
│
├─ Config-tunable value (locale, default item)
│  └─ Option: ['default', { option: true }] — override in projects[].use
│
├─ Fixtures from several modules
│  └─ mergeTests(testA, testB)
│
└─ Auth state per test file/role
   └─ test.use({ storageState: 'playwright/.auth/admin.json' })

POM-as-fixture (modern recommendation) — page objects are fine; instantiating them by hand in every test is not. Inject via fixture:

// fixtures.ts
import { test as base } from '@playwright/test';
import { TodoPage } from './pages/todo-page';

export const test = base.extend<{ todoPage: TodoPage }>({
  todoPage: async ({ page }, use) => {
    const todoPage = new TodoPage(page);
    await todoPage.goto();
    await use(todoPage);          // test body runs here
  },
});
export { expect } from '@playwright/test';

Page objects should expose locators and actions, not assertions wrapped in try/catch, and never store element handles. Details: references/fixtures-and-pom.md

Network & API

Network need?
│
├─ Stub a third-party API           → page.route('**/api/**', r => r.fulfill({ json }))
├─ Tweak a real response            → const res = await route.fetch(); route.fulfill({ response: res, json })
├─ Simulate failure / offline       → route.abort() / route.fulfill({ status: 500 })
├─ Many endpoints, real shapes      → HAR record + replay (page.routeFromHAR, update: true to record)
├─ Pure API test (no browser)       → request fixture / APIRequestContext
├─ Seed data fast, assert via UI    → hybrid: create via request, verify via page
└─ WebSocket traffic                → page.routeWebSocket(url, ws => ws.onMessage(...))

Hybrid seed-via-API, assert-via-UI — the single biggest speed win in most suites:

test('shows new project', async ({ request, page }) => {
  const res = await request.post('/api/projects', { data: { name: 'Apollo' } });
  expect(res.ok()).toBeTruthy();
  await page.goto('/projects');
  await expect(page.getByRole('link', { name: 'Apollo' })).toBeVisible();
});

Rule of thumb: mock third-party dependencies you don't own; exercise your own backend for real (or mock it deliberately in a separate "frontend-isolated" project). Details: references/network-and-api.md

Authentication

Standard pattern — login once in a setup project, reuse storageState everywhere:

// tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Username').fill(process.env.E2E_USER!);
  await page.getByLabel('Password').fill(process.env.E2E_PASS!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByTestId('user-menu')).toBeVisible();   // wait for auth to settle!
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});
Pattern Use when
One setup project + storageState in use One shared account, tests don't mutate server-side user state
Per-role files (admin.json, user.json) + test.use({ storageState }) Role-based behavior under test
Worker-scoped account fixture (testInfo.parallelIndex) Parallel tests mutate user state — one account per worker
API login (request.post + request.storageState) Login endpoint exists; 10x faster than UI login

Gotchas: add playwright/.auth/ to .gitignore. storageState captures cookies + localStorage — not sessionStorage (persist that manually via page.evaluate + init script). Always assert a logged-in signal before saving state, or you save a half-logged-in race.

Parallelism, Retries, Isolation

Knob Setting Notes
Workers workers: process.env.CI ? 1 : undefined Local: half the logical CPU cores. CI runners are small — shard machines instead of oversubscribing
File-level parallel fullyParallel: true Also makes sharding split per-test, not per-file
Sharding npx playwright test --shard=1/4 One shard per CI machine; merge blob reports after
Retries retries: process.env.CI ? 2 : 0 Pair with trace: 'on-first-retry'; treat "flaky" status as a bug queue, not a fix
Serial test.describe.configure({ mode: 'serial' }) Smell — usually means hidden inter-test coupling

Isolation discipline: every test gets a fresh context/page (cookies, storage) — keep it that way. No test reads state written by another test; shared server-side state is reset via API in beforeEach or scoped per worker (test.info().parallelIndex in usernames/tenant IDs). A suite that only passes single-worker is broken, not "sensitive".

Flake diagnosis: trace: 'on-first-retry' → npx playwright show-trace (DOM snapshots, network, console per action). Local: npx playwright test --ui or PWDEBUG=1 / page.pause(). Repro: --repeat-each=20 --workers=4. Playbook: references/flake-hunting.md

Triage a whole run without eyeballing the report — generate the JSON reporter output, then rank the offenders with the bundled triage tool (scripts/triage-flakes.py):

npx playwright test --reporter=json > results.json   # or reporter: [['json', { outputFile: 'results.json' }]]
scripts/triage-flakes.py results.json                # flaky tests first, then hard fails

It emits a ranked TSV (or --json envelope, schema claude-mods.playwright-ops.flake-triage/v1): flaky tests (passed only on retry) first — ordered by retry count then duration — followed by unexpected hard failures, each with file:line, the status sequence (failed->passed), and total duration. Exit 10 means flakes/fails were found (the triage signal — go fix them); exit 0 means a clean suite. --outcome all includes the passing tests for context; -n N caps rows.

CI (GitHub Actions)

- uses: actions/checkout@v5
- uses: actions/setup-node@v5
  with: { node-version: lts/* }
- run: npm ci
- run: npx playwright install --with-deps chromium   # only browsers you test
- run: npx playwright test
- uses: actions/upload-artifact@v4
  if: ${{ !cancelled() }}
  with: { name: playwright-report, path: playwright-report/, retention-days: 30 }
Decision Guidance
Container vs install-deps mcr.microsoft.com/playwright:vX.Y.Z-jammy image pins browser+OS (best for visual tests); install --with-deps is simpler and fine otherwise. Pin image tag to your @playwright/test version
Browser caching Cache ~/.cache/ms-playwright keyed on Playwright version; skip when using the container
Sharded reports reporter: 'blob' on shards → upload blob-report/ → merge job: npx playwright merge-reports --reporter html ./all-blob-reports
Fail-fast vs full suite PRs: fail-fast: false + --max-failures=10 per shard — see all failures in one round-trip. Smoke gates: fail fast

Full workflows (sharding matrix, merge job, caching): references/ci-patterns.md

Visual Testing

await expect(page).toHaveScreenshot('landing.png', {
  maxDiffPixels: 100,                       // or maxDiffPixelRatio / threshold
  mask: [page.getByTestId('ad-banner')],    // black-box dynamic regions
  fullPage: true,
});
  • First run generates the baseline (test fails); update with npx playwright test --update-snapshots
  • Snapshots are named per browser and platform (landing-chromium-darwin.png) — baselines generated on macOS will not match Linux CI. Fix: generate baselines inside the same Docker image CI uses, or run visual tests only in the container
  • Disable animations: toHaveScreenshot defaults animations: 'disabled'; hide dynamic bits with mask or stylePath (CSS applied at capture time)
  • Global defaults: expect: { toHaveScreenshot: { maxDiffPixels: 100 } } in config
  • toMatchSnapshot() for non-image data (text/buffers)

Component Testing & When to Prefer Cypress

@playwright/experimental-ct-react (also vue/svelte) mounts components in a real browser — still experimental; for component-level work, Vitest browser mode or Testing Library are the safer default, with Playwright covering E2E.

Factor Playwright Cypress
Browsers Chromium, Firefox, WebKit (real Safari engine) Chrome-family, Firefox; WebKit experimental
Parallelism Free, built-in, shardable Paid Cloud for parallel orchestration
Multi-tab / multi-origin / iframes Native Historically constrained
API testing Built-in request context Via cy.request, less ergonomic
Component testing Experimental Mature, first-class
In-browser interactive DX UI mode (excellent) The original benchmark; some teams still prefer it

Reach for Cypress when component testing maturity or an existing Cypress investment dominates; otherwise Playwright is the default for new E2E suites. (Repo also has a sibling cypress-ops skill.)

Debugging & Codegen

Tool Command Use
UI mode npx playwright test --ui Watch mode, time-travel, pick locators
Inspector PWDEBUG=1 npx playwright test or page.pause() Step through actions live
Codegen npx playwright codegen <url> Records actions, emits role-based locators — treat output as a draft, refactor into POMs/fixtures
Trace viewer npx playwright show-trace trace.zip Post-mortem: snapshots, network, console
Headed + slow --headed --debug Eyeball a single test
VS Code extension — Run/debug tests, pick locators in-editor

An official Playwright MCP server (@playwright/mcp) also exists for agent-driven browser automation — distinct from the test runner; don't conflate browsing automation with the test suite.

References

File Contents
references/fixtures-and-pom.md Fixture scopes/options/merging, POM-as-fixture architecture, anti-patterns
references/network-and-api.md route/fulfill/abort, HAR replay, API testing, hybrid seeding, WebSocket
references/ci-patterns.md Full GH Actions workflows: basic, sharded+merge, container, caching, reporters
references/flake-hunting.md Systematic flake diagnosis: traces, repro loops, common causes + fixes
scripts/triage-flakes.py Parse a Playwright JSON report and rank flaky/failing tests (exit 10 = findings); see Flake diagnosis above
assets/playwright.config.template.ts Commented production config template

Whether a journey belongs in e2e at all, and which tier runs it: test-engineering. This skill is the driver mechanics.

Files (claude-mods)
  • assets
    • playwright.config.template.ts 4.6 KB
      Loading…
  • references
    • ci-patterns.md 6.4 KB
      Loading…
    • fixtures-and-pom.md 6.6 KB
      Loading…
    • flake-hunting.md 5.8 KB
      Loading…
    • network-and-api.md 5.9 KB
      Loading…
  • scripts
    • .gitkeep 0 B · in bundle
    • triage-flakes.py 10.2 KB
      Loading…
  • SKILL.md 15.6 KB
    ---
    name: playwright-ops
    description: "Playwright end-to-end testing: selectors, fixtures, network mocking, auth, parallelism, CI. Use for: playwright, e2e test, end-to-end testing, browser test, getByRole, page object, storageState, trace viewer, flaky test, test sharding, visual regression, toHaveScreenshot, playwright config, codegen."
    license: MIT
    allowed-tools: "Read Write Bash"
    metadata:
      author: claude-mods
      related-skills: test-engineering, ci-cd-ops
    ---
    
    # Playwright Operations
    
    End-to-end testing with Playwright Test (`@playwright/test`, TS/JS). A Python flavor
    (`pytest-playwright`) exists with the same browser API but pytest-style fixtures — patterns here
    translate directly; runner config does not.
    
    ## Quick Start
    
    ```bash
    npm init playwright@latest          # scaffold config + example test + GH Actions workflow
    npx playwright test                 # run all tests, all projects
    npx playwright test --project=chromium --grep "@smoke"
    npx playwright test --ui            # interactive UI mode (watch, time-travel)
    npx playwright codegen https://app.local   # record actions -> generated locators
    npx playwright show-report          # open last HTML report
    npx playwright show-trace trace.zip # inspect a trace
    ```
    
    ## Selector Strategy
    
    **Hierarchy — always prefer the highest tier that uniquely matches:**
    
    | Tier | Locator | When |
    |------|---------|------|
    | 1 | `page.getByRole('button', { name: 'Submit' })` | Anything with an ARIA role — buttons, links, headings, textboxes. Tests a11y for free |
    | 2 | `page.getByLabel('Password')` | Form fields with labels |
    | 3 | `page.getByPlaceholder('name@example.com')` | Inputs without labels (fix the label instead, when you can) |
    | 4 | `page.getByText('Welcome back')` | Non-interactive text content |
    | 5 | `page.getByTestId('cart-total')` | Stable hook when semantics don't disambiguate. Configure attribute via `testIdAttribute` |
    | 6 | `page.locator('css=...')` / `xpath=` | **Last resort.** Coupled to DOM structure; breaks on refactor |
    
    Why: tiers 1–4 locate the way a user perceives the page — resilient to markup changes, and
    `getByRole` fails loudly when accessibility regresses. CSS/XPath encode implementation detail.
    
    **Narrowing without CSS:**
    
    ```ts
    page.getByRole('listitem')
        .filter({ hasText: 'Product 2' })
        .getByRole('button', { name: 'Add to cart' });
    
    page.getByRole('row').filter({ has: page.getByRole('cell', { name: 'Alice' }) });
    ```
    
    ### Web-First Assertions (no manual waits, ever)
    
    ```ts
    // BAD — checks once, races the render; sleeps are flake factories
    expect(await page.getByText('welcome').isVisible()).toBe(true);
    await page.waitForTimeout(2000);
    
    // GOOD — auto-retries until pass or timeout
    await expect(page.getByText('welcome')).toBeVisible();
    await expect(page.getByRole('list')).toHaveCount(3);
    await expect(page).toHaveURL(/\/dashboard/);
    await expect.soft(page.getByTestId('status')).toHaveText('Active'); // don't stop test on failure
    ```
    
    Actions (`click`, `fill`) auto-wait for actionability (visible, stable, enabled). If you feel the
    need for `waitForTimeout`, you're missing an assertion or an `await expect(...)` on a state change.
    For async non-DOM conditions use `expect.poll(() => fn())` or `expect(async () => {...}).toPass()`.
    
    Lint guard: enable `@typescript-eslint/no-floating-promises` — a missing `await` on an assertion is
    the most common silent-pass bug.
    
    ## Config Skeleton
    
    Full production template with comments: [assets/playwright.config.template.ts](assets/playwright.config.template.ts)
    
    ```ts
    import { defineConfig, devices } from '@playwright/test';
    
    export default defineConfig({
      testDir: './tests',
      fullyParallel: true,
      forbidOnly: !!process.env.CI,
      retries: process.env.CI ? 2 : 0,
      workers: process.env.CI ? 1 : undefined,
      reporter: process.env.CI ? 'blob' : 'html',
      use: {
        baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
        trace: 'on-first-retry',
        testIdAttribute: 'data-testid',
      },
      projects: [
        { name: 'setup', testMatch: /.*\.setup\.ts/ },
        {
          name: 'chromium',
          use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
          dependencies: ['setup'],
        },
      ],
      webServer: {
        command: 'npm run dev',
        url: 'http://localhost:3000',
        reuseExistingServer: !process.env.CI,
      },
    });
    ```
    
    ## Fixtures Decision Tree
    
    ```
    What do I need to share/setup?
    │
    ├─ Per-test object (page object, seeded record)
    │  └─ test.extend() test-scoped fixture — setup, await use(x), teardown
    │
    ├─ Expensive, safe-to-share resource (DB pool, test account)
    │  └─ Worker-scoped: [fn, { scope: 'worker' }] — once per worker process
    │
    ├─ Side effect every test needs (log capture, network stub)
    │  └─ Automatic: [fn, { auto: true }] — runs without being referenced
    │
    ├─ Config-tunable value (locale, default item)
    │  └─ Option: ['default', { option: true }] — override in projects[].use
    │
    ├─ Fixtures from several modules
    │  └─ mergeTests(testA, testB)
    │
    └─ Auth state per test file/role
       └─ test.use({ storageState: 'playwright/.auth/admin.json' })
    ```
    
    **POM-as-fixture (modern recommendation)** — page objects are fine; *instantiating them by hand in
    every test* is not. Inject via fixture:
    
    ```ts
    // fixtures.ts
    import { test as base } from '@playwright/test';
    import { TodoPage } from './pages/todo-page';
    
    export const test = base.extend<{ todoPage: TodoPage }>({
      todoPage: async ({ page }, use) => {
        const todoPage = new TodoPage(page);
        await todoPage.goto();
        await use(todoPage);          // test body runs here
      },
    });
    export { expect } from '@playwright/test';
    ```
    
    Page objects should expose **locators and actions**, not assertions wrapped in try/catch, and never
    store element handles. Details: [references/fixtures-and-pom.md](references/fixtures-and-pom.md)
    
    ## Network & API
    
    ```
    Network need?
    │
    ├─ Stub a third-party API           → page.route('**/api/**', r => r.fulfill({ json }))
    ├─ Tweak a real response            → const res = await route.fetch(); route.fulfill({ response: res, json })
    ├─ Simulate failure / offline       → route.abort() / route.fulfill({ status: 500 })
    ├─ Many endpoints, real shapes      → HAR record + replay (page.routeFromHAR, update: true to record)
    ├─ Pure API test (no browser)       → request fixture / APIRequestContext
    ├─ Seed data fast, assert via UI    → hybrid: create via request, verify via page
    └─ WebSocket traffic                → page.routeWebSocket(url, ws => ws.onMessage(...))
    ```
    
    **Hybrid seed-via-API, assert-via-UI** — the single biggest speed win in most suites:
    
    ```ts
    test('shows new project', async ({ request, page }) => {
      const res = await request.post('/api/projects', { data: { name: 'Apollo' } });
      expect(res.ok()).toBeTruthy();
      await page.goto('/projects');
      await expect(page.getByRole('link', { name: 'Apollo' })).toBeVisible();
    });
    ```
    
    Rule of thumb: **mock third-party dependencies you don't own; exercise your own backend for real**
    (or mock it deliberately in a separate "frontend-isolated" project).
    Details: [references/network-and-api.md](references/network-and-api.md)
    
    ## Authentication
    
    Standard pattern — login once in a setup project, reuse `storageState` everywhere:
    
    ```ts
    // tests/auth.setup.ts
    import { test as setup, expect } from '@playwright/test';
    
    setup('authenticate', async ({ page }) => {
      await page.goto('/login');
      await page.getByLabel('Username').fill(process.env.E2E_USER!);
      await page.getByLabel('Password').fill(process.env.E2E_PASS!);
      await page.getByRole('button', { name: 'Sign in' }).click();
      await expect(page.getByTestId('user-menu')).toBeVisible();   // wait for auth to settle!
      await page.context().storageState({ path: 'playwright/.auth/user.json' });
    });
    ```
    
    | Pattern | Use when |
    |---------|----------|
    | One setup project + `storageState` in `use` | One shared account, tests don't mutate server-side user state |
    | Per-role files (`admin.json`, `user.json`) + `test.use({ storageState })` | Role-based behavior under test |
    | Worker-scoped account fixture (`testInfo.parallelIndex`) | Parallel tests mutate user state — one account per worker |
    | API login (`request.post` + `request.storageState`) | Login endpoint exists; 10x faster than UI login |
    
    Gotchas: add `playwright/.auth/` to `.gitignore`. `storageState` captures cookies +
    localStorage — **not sessionStorage** (persist that manually via `page.evaluate` + init script).
    Always assert a logged-in signal before saving state, or you save a half-logged-in race.
    
    ## Parallelism, Retries, Isolation
    
    | Knob | Setting | Notes |
    |------|---------|-------|
    | Workers | `workers: process.env.CI ? 1 : undefined` | Local: half the logical CPU cores. CI runners are small — shard machines instead of oversubscribing |
    | File-level parallel | `fullyParallel: true` | Also makes sharding split per-test, not per-file |
    | Sharding | `npx playwright test --shard=1/4` | One shard per CI machine; merge blob reports after |
    | Retries | `retries: process.env.CI ? 2 : 0` | Pair with `trace: 'on-first-retry'`; treat "flaky" status as a bug queue, not a fix |
    | Serial | `test.describe.configure({ mode: 'serial' })` | Smell — usually means hidden inter-test coupling |
    
    **Isolation discipline:** every test gets a fresh `context`/`page` (cookies, storage) — keep it
    that way. No test reads state written by another test; shared server-side state is reset via API in
    `beforeEach` or scoped per worker (`test.info().parallelIndex` in usernames/tenant IDs). A suite
    that only passes single-worker is broken, not "sensitive".
    
    **Flake diagnosis:** `trace: 'on-first-retry'` → `npx playwright show-trace` (DOM snapshots,
    network, console per action). Local: `npx playwright test --ui` or `PWDEBUG=1` / `page.pause()`.
    Repro: `--repeat-each=20 --workers=4`. Playbook: [references/flake-hunting.md](references/flake-hunting.md)
    
    **Triage a whole run without eyeballing the report** — generate the JSON reporter output, then
    rank the offenders with the bundled triage tool ([scripts/triage-flakes.py](scripts/triage-flakes.py)):
    
    ```bash
    npx playwright test --reporter=json > results.json   # or reporter: [['json', { outputFile: 'results.json' }]]
    scripts/triage-flakes.py results.json                # flaky tests first, then hard fails
    ```
    
    It emits a ranked TSV (or `--json` envelope, schema `claude-mods.playwright-ops.flake-triage/v1`):
    flaky tests (passed only on retry) first — ordered by retry count then duration — followed by
    `unexpected` hard failures, each with `file:line`, the status sequence (`failed->passed`), and total
    duration. **Exit 10 means flakes/fails were found** (the triage signal — go fix them); exit 0 means a
    clean suite. `--outcome all` includes the passing tests for context; `-n N` caps rows.
    
    ## CI (GitHub Actions)
    
    ```yaml
    - uses: actions/checkout@v5
    - uses: actions/setup-node@v5
      with: { node-version: lts/* }
    - run: npm ci
    - run: npx playwright install --with-deps chromium   # only browsers you test
    - run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: ${{ !cancelled() }}
      with: { name: playwright-report, path: playwright-report/, retention-days: 30 }
    ```
    
    | Decision | Guidance |
    |----------|----------|
    | Container vs install-deps | `mcr.microsoft.com/playwright:vX.Y.Z-jammy` image pins browser+OS (best for visual tests); `install --with-deps` is simpler and fine otherwise. **Pin image tag to your `@playwright/test` version** |
    | Browser caching | Cache `~/.cache/ms-playwright` keyed on Playwright version; skip when using the container |
    | Sharded reports | `reporter: 'blob'` on shards → upload `blob-report/` → merge job: `npx playwright merge-reports --reporter html ./all-blob-reports` |
    | Fail-fast vs full suite | PRs: `fail-fast: false` + `--max-failures=10` per shard — see *all* failures in one round-trip. Smoke gates: fail fast |
    
    Full workflows (sharding matrix, merge job, caching): [references/ci-patterns.md](references/ci-patterns.md)
    
    ## Visual Testing
    
    ```ts
    await expect(page).toHaveScreenshot('landing.png', {
      maxDiffPixels: 100,                       // or maxDiffPixelRatio / threshold
      mask: [page.getByTestId('ad-banner')],    // black-box dynamic regions
      fullPage: true,
    });
    ```
    
    - First run generates the baseline (test fails); update with `npx playwright test --update-snapshots`
    - Snapshots are named per browser **and platform** (`landing-chromium-darwin.png`) — baselines
      generated on macOS will not match Linux CI. Fix: generate baselines inside the same Docker image
      CI uses, or run visual tests only in the container
    - Disable animations: `toHaveScreenshot` defaults `animations: 'disabled'`; hide dynamic bits with
      `mask` or `stylePath` (CSS applied at capture time)
    - Global defaults: `expect: { toHaveScreenshot: { maxDiffPixels: 100 } }` in config
    - `toMatchSnapshot()` for non-image data (text/buffers)
    
    ## Component Testing & When to Prefer Cypress
    
    `@playwright/experimental-ct-react` (also vue/svelte) mounts components in a real browser —
    **still experimental**; for component-level work, Vitest browser mode or Testing Library are the
    safer default, with Playwright covering E2E.
    
    | Factor | Playwright | Cypress |
    |--------|-----------|---------|
    | Browsers | Chromium, Firefox, WebKit (real Safari engine) | Chrome-family, Firefox; WebKit experimental |
    | Parallelism | Free, built-in, shardable | Paid Cloud for parallel orchestration |
    | Multi-tab / multi-origin / iframes | Native | Historically constrained |
    | API testing | Built-in `request` context | Via `cy.request`, less ergonomic |
    | Component testing | Experimental | Mature, first-class |
    | In-browser interactive DX | UI mode (excellent) | The original benchmark; some teams still prefer it |
    
    Reach for Cypress when component testing maturity or an existing Cypress investment dominates;
    otherwise Playwright is the default for new E2E suites. (Repo also has a sibling `cypress-ops` skill.)
    
    ## Debugging & Codegen
    
    | Tool | Command | Use |
    |------|---------|-----|
    | UI mode | `npx playwright test --ui` | Watch mode, time-travel, pick locators |
    | Inspector | `PWDEBUG=1 npx playwright test` or `page.pause()` | Step through actions live |
    | Codegen | `npx playwright codegen <url>` | Records actions, emits role-based locators — treat output as a draft, refactor into POMs/fixtures |
    | Trace viewer | `npx playwright show-trace trace.zip` | Post-mortem: snapshots, network, console |
    | Headed + slow | `--headed --debug` | Eyeball a single test |
    | VS Code extension | — | Run/debug tests, pick locators in-editor |
    
    An official Playwright MCP server (`@playwright/mcp`) also exists for agent-driven browser
    automation — distinct from the test runner; don't conflate browsing automation with the test suite.
    
    ## References
    
    | File | Contents |
    |------|----------|
    | [references/fixtures-and-pom.md](references/fixtures-and-pom.md) | Fixture scopes/options/merging, POM-as-fixture architecture, anti-patterns |
    | [references/network-and-api.md](references/network-and-api.md) | route/fulfill/abort, HAR replay, API testing, hybrid seeding, WebSocket |
    | [references/ci-patterns.md](references/ci-patterns.md) | Full GH Actions workflows: basic, sharded+merge, container, caching, reporters |
    | [references/flake-hunting.md](references/flake-hunting.md) | Systematic flake diagnosis: traces, repro loops, common causes + fixes |
    | [scripts/triage-flakes.py](scripts/triage-flakes.py) | Parse a Playwright JSON report and rank flaky/failing tests (exit 10 = findings); see Flake diagnosis above |
    | [assets/playwright.config.template.ts](assets/playwright.config.template.ts) | Commented production config template |
    
    Whether a journey belongs in e2e at all, and which tier runs it: `test-engineering`. This skill is the driver mechanics.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.