E2E Testing Patterns

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

Quick Reference

Category	Rules	Impact	When to Use
**emulate Backends**	rules/emulate-e2e.md	HIGH	FIRST CHOICE — deterministic API backends for E2E
Playwright Core	rules/e2e-playwright.md	HIGH	Semantic locators, auto-wait, flaky detection
Page Objects	rules/e2e-page-objects.md	HIGH	Encapsulate page interactions, visual regression
AI Agents	rules/e2e-ai-agents.md	HIGH	Planner/Generator/Healer, init-agents
A11y Playwright	rules/a11y-playwright.md	MEDIUM	Full-page axe-core scanning with WCAG 2.2 AA
A11y CI/CD	rules/a11y-testing.md	MEDIUM	CI gates, jest-axe unit tests, PR blocking
End-to-End Types	rules/validation-end-to-end.md	HIGH	tRPC, Prisma, Pydantic type safety

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

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

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

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

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.

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)