/testing-e2e

name: testing-e2e
license: MIT
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

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [**emulate Backends**](#emulate-backends) | `rules/emulate-e2e.md` | **HIGH** | **FIRST CHOICE — deterministic API backends for E2E** | | [Playwright Core](#playwright-core) | `rules/e2e-playwright.md` | HIGH | Semantic locators, auto-wait, flaky detection | | [Page Objects](#page-objects) | `rules/e2e-page-objects.md` | HIGH | Encapsulate page interactions, visual regression | | [AI Agents](#ai-agents) | `rules/e2e-ai-agents.md` | HIGH | Planner/Generator/Healer, init-agents | | [A11y Playwright](#accessibility-playwright) | `rules/a11y-playwright.md` | MEDIUM | Full-page axe-core scanning with WCAG 2.2 AA | | [A11y CI/CD](#accessibility-cicd) | `rules/a11y-testing.md` | MEDIUM | CI gates, jest-axe unit tests, PR blocking | | [End-to-End Types](#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: ['--a