E2E Testing Patterns

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

Quick Reference

Total: 7 rules, 4 references, 3 checklists, 3 examples, 1 script

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.

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.

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.

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.

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.

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.

End-to-End Types

Type safety across API layers to eliminate runtime type errors.

Visual Regression

Native Playwright screenshot comparison without external services.

await expect(page).toHaveScreenshot('checkout-page.png', {
  maxDiffPixels: 100,
  mask: [page.locator('.dynamic-content')],
});

See references/visual-regression.md for full configuration, CI/CD workflows, cross-platform handling, and Percy migration guide.

Key Decisions

References

Checklists

Examples

Scripts

Related Skills

• testing-unit - Unit testing patterns with mocking, fixtures, and data factories
• test-standards-enforcer - AAA and naming enforcement
• run-tests - Test execution orchestration
• 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)