v2.1.0 to v2.1.0

1 added, 1 removed. Audit A to A.

---

name: testing-e2e

license: MIT

- compatibility: "Claude Code 2.1.220+."

+ compatibility: "Claude Code 2.1.251+."

description: End-to-end testing patterns with Playwright — page objects, AI agent testing, visual regression, accessibility testing with axe-core, and CI integration. Use when writing E2E tests, setting up Playwright, implementing visual regression, or testing accessibility.

tags: [testing, e2e, playwright, accessibility, visual-regression, page-objects]

context: fork

agent: test-generator

version: 2.1.0

author: OrchestKit

user-invocable: false

disable-model-invocation: false

complexity: medium

persuasion-type: reference

targets:

- library: "@playwright/test"

version: ">=1.59.0" # 1.60 adds connectOverCDP({noDefaults}), webError.location(), consoleMessage.location()

metadata:

category: document-asset-creation

allowed-tools:

- Read

- Glob

- Grep

- WebFetch

- WebSearch

path_patterns: ["**/e2e/**", "**/playwright/**", "**/cypress/**", "playwright.config.*"]

---

# E2E Testing Patterns

End-to-end testing with Playwright 1.59+, visual regression, accessibility, and AI agent workflows.

## Quick Reference

|----------|-------|--------|-------------|

**Total: 7 rules, 2 references, 3 checklists, 1 example, 1 script**

## Upstream coverage (do not restate)

Playwright, axe-core and jest-axe document themselves. This skill carries only the

OrchestKit delta (`references/ork-delta.md`) plus the house subsets in `rules/`. Fetch

the vendor page for anything below instead of expecting it here.

| Topic | Source |

|-------|--------|

| Screenshot comparison workflow, baseline files, `snapshotPathTemplate` | https://playwright.dev/docs/test-snapshots |

| `toHaveScreenshot` options: `mask`, `maxDiffPixelRatio`, `stylePath`, `animations` | https://playwright.dev/docs/api/class-pageassertions |

| Auth reuse: `storageState`, setup projects, IndexedDB | https://playwright.dev/docs/auth |

| Network interception with `page.route` (the house default is still emulate first, see `rules/emulate-e2e.md`) | https://playwright.dev/docs/mock |

| Removed and changed APIs per release (SKILL.md keeps only the short denylist below) | https://playwright.dev/docs/release-notes |

| Full locator API surface (the house priority ladder stays in `rules/e2e-playwright.md`) | https://playwright.dev/docs/locators |

| Playwright runner setup on CI (the house a11y gate workflow stays in `rules/a11y-testing.md`) | https://playwright.dev/docs/ci |

| `init-agents` CLI flags and generated files (the Planner/Generator/Healer workflow stays in `rules/e2e-ai-agents.md`) | https://playwright.dev/docs/test-agents |

| `jest-axe` matcher and `configureAxe` API (the house component-state subset stays in `rules/a11y-testing.md`) | https://github.com/NickColley/jest-axe |

| Lighthouse CI configuration and score assertions | https://github.com/GoogleChrome/lighthouse-ci |

WCAG 2.2 success criteria and the manual keyboard / screen-reader / contrast / zoom

passes are NOT routed away: `checklists/a11y-testing-checklist.md` still carries them

in full, with https://www.w3.org/WAI/WCAG22/quickref/ as the normative reference.

## emulate Backends

For E2E tests that interact with external APIs (GitHub, Vercel, Google), **use emulate as the backend** instead of hitting real APIs. This eliminates flakiness from rate limits, network issues, and non-deterministic data.

| Approach | Result |

|----------|--------|

| **emulate backends** (FIRST CHOICE) | Deterministic, fast, CI-friendly |

| Real APIs | Flaky, rate-limited, slow |

| MSW/Nock intercepts | No state machines, manual response management |

Key features: seed config for reproducible data, per-worker port isolation for parallel Playwright, full state machine transitions.

See `rules/emulate-e2e.md` for patterns, CI configuration, and per-worker isolation fixtures.

---

## Playwright Quick Start

```typescript

import { test, expect } from '@playwright/test';

test('user can complete checkout', async ({ page }) => {

await page.goto('/products');

await page.getByRole('button', { name: 'Add to cart' }).click();

await page.getByRole('link', { name: 'Checkout' }).click();

await page.getByLabel('Email').fill('test@example.com');

await page.getByRole('button', { name: 'Submit' }).click();

await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();

});

```

**Locator Priority:** `getByRole()` > `getByLabel()` > `getByPlaceholder()` > `getByTestId()`

## Playwright Core

Semantic locator patterns and best practices for resilient tests.

| Rule | File | Key Pattern |

|------|------|-------------|

| Playwright E2E | `rules/e2e-playwright.md` | Semantic locators, auto-wait, new 1.58+ features |

Anti-patterns (FORBIDDEN):

- Hardcoded waits: `await page.waitForTimeout(2000)`

- CSS selectors for interactions: `await page.click('.submit-btn')`

- XPath locators

Removed in 1.58/1.59 — do NOT use:

- `_react=ComponentName[prop=value]` and `_vue=...` component selector engines — **removed in 1.58**

- `:light` selector suffix — **removed**

- `launch({ devtools: true })` option — **removed**; use `args: ['--auto-open-devtools-for-tabs']`

## Page Objects

Encapsulate page interactions into reusable classes.

| Rule | File | Key Pattern |

|------|------|-------------|

| Page Object Model | `rules/e2e-page-objects.md` | Locators in constructor, action methods, assertion methods |

```typescript

const checkout = new CheckoutPage(page);

await checkout.fillEmail('test@example.com');

await checkout.submit();

await checkout.expectConfirmation();

```

## AI Agents

Playwright 1.59+ AI agent framework for test planning, generation, and self-healing. Includes a **token-efficient CLI mode** designed for coding agents — minimal output, structured responses, reduced context overhead.

| Rule | File | Key Pattern |

|------|------|-------------|

| AI Agents | `rules/e2e-ai-agents.md` | Planner, Generator, Healer workflow |

```bash

npx playwright init-agents --loop=claude # For Claude Code

```

**Token-efficient CLI mode** (1.58+): Playwright ships a SKILL-focused CLI mode that produces compact, agent-friendly output — use this when running Playwright from AI agents to minimize token consumption.

Workflow: Planner (explores app, creates specs) -> Generator (reads spec, tests live app) -> Healer (fixes failures, updates selectors).

**New in Playwright 1.59 (Apr 2026) — relevant for AI agents:**

- `page.screencast({ start, stop, showActions })` — unified video + real-time JPEG frame streaming. Lets a Healer agent read frames mid-run for visual assertion without writing video files.

- `browser.bind()` / `npx playwright-cli attach` — attach to a running browser from an MCP client mid-test; useful for Healer to inspect a hung or failing CI run.

- `locator.normalize()` — rewrites a brittle locator to best-practice equivalents. Pair with Healer to auto-upgrade `getByTestId` → `getByRole` where possible.

## Accessibility (Playwright)

Full-page accessibility validation with axe-core in E2E tests.

| Rule | File | Key Pattern |

|------|------|-------------|

| Playwright + axe | `rules/a11y-playwright.md` | WCAG 2.2 AA, interactive state testing |

```typescript

import AxeBuilder from '@axe-core/playwright';

test('page meets WCAG 2.2 AA', async ({ page }) => {

await page.goto('/');

const results = await new AxeBuilder({ page })

.withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])

.analyze();

expect(results.violations).toEqual([]);

});

```

## Accessibility (CI/CD)

CI pipeline integration and jest-axe unit-level component testing.

| Rule | File | Key Pattern |

|------|------|-------------|

| CI Gates + jest-axe | `rules/a11y-testing.md` | PR blocking, component state testing |

## End-to-End Types

Type safety across API layers to eliminate runtime type errors.

| Rule | File | Key Pattern |

|------|------|-------------|

| Type Safety | `rules/validation-end-to-end.md` | tRPC, Zod, Pydantic, schema rejection tests |

## Visual Regression

Native Playwright screenshot comparison without external services.

```typescript

await expect(page).toHaveScreenshot('checkout-page.png', {

maxDiffPixels: 100,

mask: [page.locator('.dynamic-content')],

});

```

House rules that the vendor docs do not state (CI-only baselines, single snapshot

project, mask over threshold): `references/ork-delta.md`. Option reference and the

baseline workflow itself: see the Upstream coverage table above.

## Key Decisions

| Decision | Recommendation |

|----------|----------------|

| E2E framework | Playwright 1.59+ with semantic locators |

| Locator strategy | `getByRole` > `getByLabel` > `getByTestId` |

| Browser | Chromium (Chrome for Testing in 1.59+) |

| Page pattern | Page Object Model for complex pages |

| Visual regression | Playwright native `toHaveScreenshot()` |

| A11y testing | axe-core (E2E) + jest-axe (unit) |

| CI retries | 2-3 in CI, 0 locally |

| Flaky detection | `failOnFlakyTests: true` in CI |

| AI agents | Planner/Generator/Healer via `init-agents` |

| Type safety | tRPC for end-to-end, Zod for runtime validation |

## References

| Resource | Description |

|----------|-------------|

| `references/ork-delta.md` | House rules the vendor docs do not state: jest-axe over vitest-axe, CLI-only agent init, CI-only baselines, single snapshot project, mask over threshold |

| `references/playwright-setup.md` | Installation, MCP server, seed tests, agent initialization |

## Checklists

| Checklist | Description |

|-----------|-------------|

| `checklists/e2e-checklist.md` | Locator strategy, page objects, CI/CD, visual regression |

| `checklists/e2e-testing-checklist.md` | Comprehensive: planning, implementation, SSE, responsive, maintenance |

| `checklists/a11y-testing-checklist.md` | Automated + manual: keyboard, screen reader, color contrast, WCAG |

## Examples

| Example | Description |

|---------|-------------|

| `examples/orchestkit-e2e-tests.md` | OrchestKit analysis flow: page objects, SSE progress, error handling |

Generic Playwright samples (user flows, auth fixtures, API mocking, multi-tab, file

upload, axe scans) now come from the vendor pages in the Upstream coverage table.

## Scripts

| Script | Description |

|--------|-------------|

| `scripts/create-page-object.md` | Generate Playwright page object with auto-detected patterns |

## Related Skills

- `testing-unit` - Unit testing patterns with mocking, fixtures, and data factories

- `testing-integration` - API boundary and contract testing

- `cover` - Generates the E2E tier when the suite does not exist yet

- `verify` - Grades an existing suite and returns a merge verdict

- `expect` - Diff-aware browser verification via agent-browser

- `emulate-seed` - Seed configuration authoring for emulate providers

- `portless` (upstream) - Stable HTTPS `baseURL` for local E2E tests (`https://myapp.localhost` instead of port guessing; HTTPS-on-443 default since portless 0.10)