/a11y-playwright-testing

name: a11y-playwright-testing
description: 'Accessibility testing for web applications using Playwright (@playwright/test), TypeScript, and axe-core. Use to write, run, or debug WCAG 2.2 AA checks, keyboard and focus tests, ARIA/semantic validation, accessible names, form labels, color contrast, or screen-reader test patterns. Keywords: accessibility, WCAG, axe-core, keyboard navigation, focus management, ARIA.'
license: 'Complete terms in LICENSE.txt'

Playwright Accessibility Testing (TypeScript)

Comprehensive toolkit for automated accessibility testing using Playwright with TypeScript and axe-core. Enables WCAG 2.2 Level AA compliance verification (superset of 2.1), keyboard operability testing, semantic validation, and accessibility regression prevention.

> **Activation:** This skill is triggered when working with accessibility testing, WCAG compliance, axe-core scans, keyboard navigation tests, focus management, ARIA validation, or screen reader compatibility.

When to Use This Skill

• **Automated a11y scans** with axe-core for WCAG 2.2 AA compliance
• **Keyboard navigation tests** for Tab/Enter/Space/Escape/Arrow key operability
• **Focus management** validation for dialogs, menus, and dynamic content
• **Semantic structure** assertions for landmarks, headings, and ARIA
• **Form accessibility** testing for labels, errors, and instructions
• **Color contrast** and visual accessibility verification
• **Screen reader** compatibility testing patterns

Do NOT Use For

• Selenium/Java accessibility testing (use `accessibility-selenium-testing`).
• Authoring Playwright functional/UI E2E specs (use `playwright-e2e-testing`).
• Full conformance sign-off — automated axe scans catch ~30-40% of issues; manual audit + assistive-tech testing is still required.

Prerequisites

| Requirement | Details | | ----------- | ------------------------------ | | Node.js | v18+ recommended | | Playwright | `@playwright/test` installed | | axe-core | `@axe-core/playwright` package | | TypeScript | Configured in project |

Quick Setup

# Add axe-core to existing Playwright project
npm install -D @axe-core/playwright axe-core

First Questions to Ask

Before writing accessibility tests, clarify:

1. **Scope**: Which pages/flows are in scope? What's explicitly excluded? 2. **Standard**: WCAG 2.2 AA (default) or specific organizational policy? 3. **Priority**: Which components are highest risk (forms, modals, navigation, checkout)? 4. **Exceptions**: Known constraints (legacy markup, third-party widgets)? 5. **Assistive Tech**: Which screen readers/browsers need manual testing?

---

Core Principles

1. Automation Limitations

> [!] **Critical**: Automated tooling can detect ~30-40% of accessibility issues. Use automation to prevent regressions and catch common failures; **manual audits are required** for full WCAG conformance.

2. Semantic HTML First

Prefer native HTML semantics over ARIA. Use ARIA only when native elements cannot achieve the required semantics.

// [ok] Semantic HTML - inherently accessible
await page.getByRole("button", { name: "Submit" }).click();

// [no] ARIA override - requires manual keyboard/focus handling
await page.locator('[role="button"]').click(); // Often a <div>

3. Locator Strategy as A11y Signal

If you **cannot locate an element by role or label**, it's often an accessibility defect.

| Locator Success | Accessibility Signal | | -------------------------------------------- | -------------------------- | | `getByRole('button', { name: 'Submit' })` [ok] | Button has accessible name | | `getByLabel('Email')` [ok] | Input properly labeled | | `getByRole('navigation')` [ok] | Landmark exists | | `locator('.submit-btn')` [!] | May lack accessible name |

---

Key Workflows

Automated Axe Scan (WCAG 2.2 AA)

import AxeBuilder from "@axe-core/playwright";
import { test, expect } from "@playwright/test";

test("page has no WCAG 2.2 AA violations", async ({ page }) => {
  await page.goto("/");

  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
    .analyze();

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

Scoped Axe Scan (Component-Level)

test("form component is accessible", async ({ page }) => {
  await page.goto("/contact");

  const results = await new AxeBuilder({ page })
    .include("#contact-form") // Scope to specific component
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
    .analyze();

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

Keyboard Navigation Test

test("form is keyboard navigable", async ({ page }) => {
  await page.goto("/login");

  // Tab to first field
  await page.keyboard.press("Tab");
  await expect(page.getByLabel("Email")).toBeFocused();

  // Tab to password
  await page.keyboard.press("Tab");
  await expect(page.getByLabel("Password")).toBeFocused();

  // Tab to submit button
  await page.keyboard.press("Tab");
  await expect(page.getByRole("button", { name: "Sign in" })).toBeFocused();

  // Submit with Enter
  await page.keyboard.press("Enter");
  await expect(page).toHaveURL(/dashboard/);
});

Dialog Focus Management

test("dialog traps and returns focus", async ({ page }) => {
  await page.goto("/settings");
  const trigger = page.getByRole("button", { name: "Delete account" });

  // Open dialog
  await trigger.click();
  const dialog = page.getByRole("dialog");
  await expect(dialog).toBeVisible();

  // Focus should be inside dialog
  await expect(dialog.getByRole("button", { name: "Cancel" })).toBeFocused();

  // Tab should stay trapped in dialog
  await page.keyboard.press("Tab");
  await expect(dialog.getB