菜单
Use when you need to run real accessibility tests — Playwright keyboard interactions, axe-core scanning, visual regression, and WCAG 2.2 compliance checks. The measurement layer that feeds evidence into a11y-critic reviews.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Orchestrate the a11y accessibility lifecycle: scout → plan → critique → [perspective audit] → test → critique. Dual-mode: full lifecycle automation or step-by-step dispatch. Spawns specialist agents at depth-1 from the main session.
Evaluate a Drupal accessibility patch end-to-end: baseline evidence, patch hygiene, after-patch verification, manual/AT checks, critic gate, and upstream handoff. Evidence-gated — never VERIFIED without before/after proof under the same conditions.
Use when you have an existing component, flow, or interface and need an evidence-backed accessibility design review after basic checks pass. Best for WCAG 2.2 compliance, focus management, ARIA pattern quality, semantics, and state communication gaps automated tools miss.
Deep accessibility review from 7 access perspectives — activated by escalation from a11y-planner or a11y-critic when one or more perspectives are flagged at MEDIUM or HIGH alarm level.
Use when you know what component, flow, or interface you need but not yet the right accessibility approach. Best for turning WCAG 2.2 requirements into an accessible implementation plan with WAI-ARIA APG patterns before code hardens bad interaction and state patterns.
Use when you know what component, flow, or interface you need but not yet the right accessibility approach. Best for turning WCAG 2.2 requirements into an accessible implementation plan with WAI-ARIA APG patterns before code hardens bad interaction and state patterns.
| name | a11y-test |
| description | Use when you need to run real accessibility tests — Playwright keyboard interactions, axe-core scanning, visual regression, and WCAG 2.2 compliance checks. The measurement layer that feeds evidence into a11y-critic reviews. |
| license | Apache-2.0 |
| compatibility | Claude Code-compatible; protocol is model-agnostic |
| metadata | {"author":"zivtech","version":"1.2.0"} |
Pick the right execution mode from the routing table before running anything (the table is the source of truth — don't trust remembered mode counts):
| Task | Tool | Why |
|---|---|---|
| Codified CI keyboard tests, visual regression, axe-core scans, WCAG compliance suites | npx playwright test with .spec.js files | Real keyboard events, CI-runnable, version-controlled, reproducible. Primary path — all mandatory rules below still apply. |
| Interactive agent-driven reconnaissance: snapshot ARIA structure, navigate a SPA to reach the page under test, verify a fix in place, capture annotated screenshots, probe a disclosure/menu/modal without writing a test file | agent-browser CLI (snapshot+ref pattern, persistent CDP daemon, real keyboard events) | One shell call per action, no test-file overhead, returns @e1-style refs that map directly to actions. See "Interactive reconnaissance with agent-browser" below. |
| Generate a test script from a prose spec ("test that this modal traps focus and Escape closes it") | /webwright:run or /webwright:craft (Claude Code plugin) | LLM generates complete Python Playwright script. Review before trusting. Also captures aria_snapshot() for deep ARIA tree inspection. See "Test script generation with Webwright" below. |
| Goal-driven journey audit of a live URL — "can a keyboard-only or screen-reader user complete this task?" — with evidence artifacts | keyboard-a11y-tester (external clone, pinned release 0.5.0; deterministic runner + agent-driven serve/step loop) | URL + goal in, evidence-linked WCAG findings out — no test file needed. Emulated screen-reader announcements, live-region capture, and focus-indicator measurement at the page/journey level that no other mode provides. See "Goal-driven journey audits with keyboard-a11y-tester" below. |
| Component/unit-level screen-reader assertions — accessible names, reading order, live-region announcements — in the project's own test suite (Vitest/Jest+jsdom or a browser page), no URL or journey needed | @guidepup/virtual-screen-reader (npm devDependency, exact-pinned 0.32.1) | Per-component, per-PR spoken-output evidence in milliseconds — the implement→test layer keyboard-a11y-tester can't reach (it needs a deployed URL). Synthetic interactions: never keyboard-operability evidence. See "Component screen-reader assertions with virtual-screen-reader" below. |
| Visual inspection, DOM queries from a conversational session | agent-browser screenshot / agent-browser screenshot --annotate / agent-browser snapshot | Same daemon, no test runner needed. |
| Anything requiring real keyboard event delivery through an MCP wrapper | DO NOT USE Playwright MCP. Its browser_press_key calls are silently dropped for most interactive widgets. Use npx playwright test or agent-browser instead. |
Decision flowchart:
Do you have a prose description of what to test, but no test script yet?
YES → /webwright:run (one-shot) or /webwright:craft (reusable parameterized tool)
NO, you need to run an existing test → npx playwright test
NO, you need to audit a live URL against a user goal (journey, announcements, focus indicators) → keyboard-a11y-tester
NO, you need to assert component announcements, names, or reading order in unit tests (no URL yet) → virtual-screen-reader
NO, you need to explore interactively → agent-browser
CDP keyboard event delivery for agent-browser has been verified end-to-end on both a vanilla JS disclosure widget (WAI-ARIA APG disclosure-faq example: focus → press Enter → aria-expanded: false → true) and a React state-driven modal (react.dev DocSearch: Meta+K → React global keydown listener → state-mounted searchbox). The MCP keyboard delivery bug does not apply to agent-browser because it calls CDP Input.dispatchKeyEvent directly rather than through an MCP wrapper.
For ad-hoc a11y probing inside a conversational session — before writing a .spec.js file, when verifying a single fix, or when exploring the ARIA structure of an unfamiliar component — use agent-browser. The snapshot+ref pattern eliminates locator hunting:
agent-browser open https://example.com/component-under-test
agent-browser snapshot -i # Returns interactive elements with refs: [ref=e1], [ref=e2]...
agent-browser focus @e1 # Focus by ref
agent-browser press Enter # Real CDP keyboard event
agent-browser get attr @e1 aria-expanded # Verify state mutation
agent-browser screenshot --annotate # Numbered overlays mapping to refs (useful for multimodal review)
agent-browser close
Key flags: --profile Default (reuse the user's Chrome login state for authenticated sites), --session <name> (isolated browser per parallel agent), --json (parseable output for programmatic checks), --allowed-domains (safety).
Keyboard-driving discipline (applies to all interactive modes, this one included): never send a pre-counted sequence of Tabs. Snapshot/observe, then act on what is actually focused — "Tab until the focused control is named X" is right; "Tab 6 times" is wrong. Confirm success by state change (attribute flip, URL change, announcement), not assumption.
When to escalate to npx playwright test: when the verification needs to live in CI, run across PR builds, or exercise the 12 APG widget pattern templates below. Reconnaissance with agent-browser is for interactive probing; codified regression still belongs in .spec.js files.
When to use: You have a prose a11y requirement (from the planner or a ticket) and need a runnable test script, without hand-writing it.
What it produces: A Python Playwright script with navigation, keyboard interactions, ARIA state assertions, and screenshots. Webwright generates sync_playwright scripts by default — if you need async for an existing test harness, specify in the prompt.
Language mismatch warning: Webwright generates Python. Existing CI is Node.js/.spec.js. Generated scripts are starting points — for CI, port logic to .spec.js using the APG templates below, or run Python directly if a Python test runner is available.
Example /webwright:run (actual prompt that produced a passing dialog focus trap test in benchmark):
/webwright:run Navigate to https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/.
Open the modal by clicking the trigger button.
Verify focus moves into the modal.
Tab through all focusable elements and verify focus wraps (focus trap).
Press Escape and verify the modal closes and focus returns to the trigger.
Quality gate: The operator must review generated scripts before trusting results. Check that:
page.keyboard.press() or locator.press(), NOT synthetic dispatchEventtime.sleep() > 5 seconds or hardcoded waits that mask timing issuesARIA snapshot capability: Webwright's Playwright environment captures page.locator("body").aria_snapshot() — the full accessibility tree with roles, states, and relationships as structured YAML. Richer than agent-browser snapshot -i for structural analysis (captures all 4 tab→panel relationships via aria-controls/aria-labelledby cross-references, vs. agent-browser which shows only interactive element refs).
Limitations:
Benchmark results (2026-05-26): 25/25 across 5 WAI-ARIA APG tasks (dialog focus trap, tabs ARIA state, axe-core injection, menu keyboard navigation, ARIA tree inspection). All scripts used real page.keyboard.press() calls. Full results in evals/suites/webwright-benchmark/.
Prerequisites: Python 3.10+, Playwright Python (pip install playwright && playwright install chromium)
Two-step install:
/plugin marketplace add microsoft/Webwright/plugin install webwright@webwrightIf marketplace fails: git clone https://github.com/microsoft/Webwright && /plugin install ./Webwright
Platform note: Claude Code plugin only. Not available in Codex CLI. From Codex, the usable browser automation options are agent-browser and keyboard-a11y-tester (both plain CLIs). Generated .py scripts can be executed from Codex via python3 script.py.
When to use: you have a live URL and a task in plain words ("can a keyboard-only or screen-reader user complete X?") and need evidence-linked WCAG findings without writing a test file — discovery audits, before/after patch evidence, whole-journey reviews. When NOT to use: widget CI regression (→ .spec.js + the APG templates), quick probing or authenticated Chrome-profile flows (→ agent-browser), rule scans (→ axe-core, §4).
What it is: ezufelt/keyboard-a11y-tester — an external tool, adopted at release 0.5.0 (commit 7e852a7, MIT; originally adopted at 97eb13e, bumped 2026-07-11 after upstream merged our PR #7 and began tagging releases — re-verify on every upgrade). Two layers: a deterministic Playwright/CDP runner (real keyboard events only, never .click(); machine-decidable WCAG checks; dual-signal focus-indicator measurement) and an emulated screen-reader persona (@guidepup/virtual-screen-reader: announcement capture, live-region monitoring, reading-order census). Runs both W3C personas (keyboard "Ade", screen-reader "Lakshmi") in one pass. As of 0.5.0 it also detects broken ARIA ID references and keyboard-focusable controls missing from the accessibility tree, includes our 3.3.2 UA-default-name check, and supports authenticated runs via --storage-state <playwright-storageState.json> (agent-browser remains the route when you want to reuse the user's real Chrome profile instead of exporting state). Cross-validated against this repo's 33 critic fixtures on 2026-07-10 — agreement record: evals/results/keyboard-a11y-tester/README.md.
git clone https://github.com/ezufelt/keyboard-a11y-tester && cd keyboard-a11y-tester
git checkout 0.5.0 # adopted pin (tagged release)
npm install && node scripts/setup-check.mjs # npx playwright install chromium only if browser_available=false
The upstream Claude Code plugin flow (/plugin marketplace add ezufelt/keyboard-a11y-tester) exists but is unverified here; the clone path works from both Claude Code and Codex.
# Batch blind Tab-crawl (unattended; never presses Enter/Space) — per viewport:
node scripts/runner.mjs --url https://site --viewport desktop --max-steps 40 --out <dir>
# Driven session (the value center — the agent decides every keystroke):
node scripts/runner.mjs serve --url https://site --goal "find and submit the contact form" \
--viewport desktop --port 9333 # default port is 9333 (9400 in upstream examples is just an example)
# prints: READY <session-dir>
node scripts/runner.mjs observe <session-dir>
node scripts/runner.mjs step <session-dir> --press Tab # one key → AX name/role/state, focus style, sr_announcement
node scripts/runner.mjs step <session-dir> --type "hello@example.com"
node scripts/runner.mjs finish <session-dir> && node scripts/runner.mjs stop <session-dir>
Core discipline: observe → decide → act (see the keyboard-driving rule in the agent-browser section — it originated here). Read sr_announcement.live_announcements after any action that visibly changes the page: an entry proves the update reaches a screen reader; its absence after a visible change is 4.1.3 failure evidence.
--out)trace.json — per step: keystroke, selector, CDP AX name/role/state, computed focus style, focus_moved, screenshot ref, sr_announcementdeterministic-findings.json — {wcag, persona, conformance_level, confidence, severity, url, locations, persona_impact, evidence[]}screen-reader-census.json — whole-page reading order (spoken phrase, role, selector) + declared live regionsscreenshots/step_NNNN.png — focused-region cropsThese are measured test evidence for a11y-critic reviews (formal Phase 0 tier wiring lands with assessment Phase 3).
live_announcements.<input type=file> reports AX name "Choose File", so the unnamed-control check stays quiet. Label association still needs axe/static/judgment review.97eb13e and 0.5.0) — one more reason never to gate on it.serious → MAJOR (CRITICAL if it blocks the goal); moderate → MINOR or MAJOR by user impact; minor/AAA-informative → ENHANCEMENTid embeds the viewport and is run-scoped — don't use it)keyboard → keyboard_motor; screen-reader → screen_reader_semantictrace.json step_0003: outline 3px solid; AAA contrast 2.34)navigator.webdriver (page-scoped) so the CAPTCHA can initialize — automation-signal spoofing that can trip a WAF or security review. Get explicit client sign-off before pointing it at client production infrastructure; prefer staging.npx playwright test.When to use: you're implementing or fixing a component and need to assert what a screen reader computes and announces — accessible names, reading order, live-region announcements — in the project's own test suite, per PR, with no URL, journey, or deployed page. This is the implement → test layer: the cheapest point to catch the toast/async-status defect class. When NOT to use: keyboard operability (its interactions are synthetic user-event events — real-key evidence stays with .spec.js, agent-browser, or keyboard-a11y-tester), anything visual (jsdom has no layout), page/journey audits (→ keyboard-a11y-tester), rule scans (→ axe-core, §4), open-shadow-DOM components (invisible to it — upstream #182), aria-busy states (unsupported — upstream #36).
What it is: guidepup/virtual-screen-reader — a screen-reader simulator as a library (MIT; adopted at npm 0.32.1, exact-pinned). Walks the accessibility tree of any DOM, emits spoken phrases ("button, Save document"), captures live-region announcements with politeness prefixes ("polite: Draft saved"), and exposes SR quick-key emulation via virtual.perform(virtual.commands.*) — moveToNextHeading, moveToNextLandmark, per-level heading jumps, jumpToErrorMessageElement (aria-errormessage), aria-flowto reading-order commands. Spec-anchored (ACCNAME 1.2, CORE-AAM, HTML-AAM, WAI-ARIA 1.2) and WPT-tested upstream. It is already this stack's transitive SR engine inside keyboard-a11y-tester; this lane uses it directly. Validated in-repo 2026-07-11 in three environments — plain Node+jsdom, Vitest 4 jsdom environment, real Chromium via its ESM build: docs/virtual-screen-reader-adoption-assessment.md. Jest+jsdom is expected to match Vitest but was not run; Storybook is expected but unverified — treat neither as a validated path until someone runs it.
npm install --save-dev @guidepup/virtual-screen-reader@0.32.1 # exact pin; re-verify calibration rules on any bump
import { afterEach, expect, test } from "vitest";
import { virtual } from "@guidepup/virtual-screen-reader";
afterEach(async () => {
await virtual.stop().catch(() => {}); // stateful singleton — mandatory, or phrase logs leak across tests
document.body.innerHTML = "";
});
// 1. Announcement assertion — persistent-container pattern (the only reliable shape; see rule 3)
test("saving announces to screen reader users", async () => {
document.body.innerHTML = `
<main><button>Save</button></main>
<div role="status" id="app-status"></div> <!-- persistent, empty at mount -->
`;
await virtual.start({ container: document.body });
document.getElementById("app-status").textContent = "Item saved";
await Promise.resolve(); // microtask flush suffices (measured) — no arbitrary sleep needed
expect(await virtual.spokenPhraseLog()).toContain("polite: Item saved");
});
// 2. Reading-order / name assertions — bounded walk (never while-true; see rule 1)
test("reads the expected sequence", async () => {
document.body.innerHTML = `<h2>Cart</h2><p>$29.00</p><button>Buy now</button>`;
await virtual.start({ container: document.body });
const phrases = [];
for (let i = 0; i < 40; i++) { // max-step guard: aria-modal traps the cursor by design
await virtual.next();
const p = await virtual.lastSpokenPhrase();
phrases.push(p);
if (p === "end of document") break;
}
expect(phrases.indexOf("$29.00")).toBeLessThan(phrases.indexOf("button, Buy now"));
});
aria-modal="true" is present (jsdom). The cursor traps inside the modal by design (upstream #54) — the walk never terminates. Scope container to the component and bound every walk with a max-step guard.element.shadowRoot exists anywhere under the container, VSR evidence is partial: route to keyboard-a11y-tester or browser testing instead.role="alert" element. Removal splits on aria-atomic (measured, fixture sweep): clearing a non-atomic region is silent; clearing an aria-atomic="true" region announces an empty "polite: " phrase — an empty polite entry is a region-clear marker, not noise. Interpretive context (domain knowledge, not probed here): real screen readers are also inconsistent on pre-populated alert insertion, which is why robust toast guidance uses a persistent container. Consequences: assert via the persistent-container pattern; a silent log after mount-with-content of an alert is inconclusive, not proof the fix failed; buggy-component silence is defect evidence only alongside the structural fact (no role/aria-live present).start() resolves but log reads hang forever, and the wedged state cascades hangs into every later test in the file, teardown included. Never enable fake timers in a file that runs VSR. Components needing fake timers (auto-dismiss toasts) get announcement assertions in a separate real-timer file — natural with the persistent-container pattern (assert the announcement on show; the timed dismiss is a separate concern).vsr@0.32.1 <test file>). Both consumption routes are frozen (this exact pin; keyboard-a11y-tester's committed lockfile), so skew arises only on deliberate upgrade — the citation makes it detectable. Re-verify rules 1–4 on any version bump.The artifacts are spoken-phrase logs plus the asserting test file — a11y-critic Phase 0 hard evidence (gate passed 2026-07-11: evals/results/virtual-screen-reader/; contract mapping in docs/a11y-evidence-finding-contract.md). Cite tool version + test file + the exact phrase or its absence, and pair silence with the structural fact (no role/aria-live present). Platform note: plain npm library — works from Claude Code and Codex.
MANDATORY: All keyboard tests MUST use real Playwright keyboard interactions against a live or local site. Never check ARIA attributes alone and claim a keyboard test passed — you must actually press keys and verify the result.
page.keyboard.press('Enter'), page.keyboard.press('Tab'), page.keyboard.press('Escape'), page.keyboard.press('Space') for single keyspage.keyboard.press('Shift+ArrowRight'), page.keyboard.press('Control+Enter'), page.keyboard.press('Meta+Enter') for key combospage.keyboard.down('Shift') / page.keyboard.up('Shift') with page.keyboard.press('ArrowRight') for held-key sequences (e.g., text selection)element.focus() then verify with toBeFocused() or document.activeElement === elementdispatchEvent(new KeyboardEvent(...)) to test keyboard features — that bypasses the real browser keyboard path and proves nothingwindow.getSelection()Every keyboard test must follow this pattern:
1. Record initial state (aria-expanded, aria-pressed, visibility, activeElement)
2. Perform real keyboard action (page.keyboard.press)
3. Wait for UI to update (waitForTimeout or waitForFunction)
4. Verify state actually changed (attribute toggled, element visible/hidden, focus moved)
Example — testing a toggle button:
const btn = page.locator('button[aria-expanded]');
const initialExpanded = await btn.getAttribute('aria-expanded');
await btn.focus();
await page.keyboard.press('Enter');
await page.waitForTimeout(300);
const afterExpanded = await btn.getAttribute('aria-expanded');
expect(initialExpanded).not.toBe(afterExpanded); // State MUST change
Reusable Playwright templates for common widget patterns. Each uses real page.keyboard.press() calls — never synthetic events.
1. Tree View
Interactions: ArrowDown/Up move aria-activedescendant; ArrowRight expands closed node or moves to first child; ArrowLeft collapses open node or moves to parent; Home/End jump to first/last visible treeitem; Enter activates.
const tree = page.locator('[role="tree"]');
await tree.focus();
const before = await tree.getAttribute('aria-activedescendant');
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(200);
const after = await tree.getAttribute('aria-activedescendant');
expect(after).not.toBe(before);
expect(after).toBeTruthy(); // must reference a [role="treeitem"] id
2. Roving Tabindex (Tabs)
Interactions: ArrowRight/Left move focus between [role="tab"] elements and update tabindex; active tab keeps tabindex="0", others get tabindex="-1"; only one aria-selected="true" per [role="tablist"].
const activeTab = page.locator('[role="tab"][tabindex="0"]');
await activeTab.focus();
await page.keyboard.press('ArrowRight');
await page.waitForTimeout(200);
const newActive = page.locator('[role="tab"][tabindex="0"]');
await expect(newActive).toHaveAttribute('aria-selected', 'true');
expect(await page.locator('[role="tab"][aria-selected="true"]').count()).toBe(1);
3. Dialog Focus Trap
Interactions: Tab/Shift+Tab cycle within [role="dialog"] (last focusable→first, first→last); Escape closes; focus returns to trigger after close.
await triggerButton.click();
const dialog = page.locator('[role="dialog"]');
// Tab past last focusable item — should wrap to first
const focusables = dialog.locator('button, [href], input, [tabindex="0"]');
const count = await focusables.count();
for (let i = 0; i < count; i++) await page.keyboard.press('Tab');
await expect(focusables.first()).toBeFocused();
await page.keyboard.press('Escape');
await expect(triggerButton).toBeFocused();
4. Sidebar/Panel Focus Management Interactions: Close button receives focus on panel open; Escape closes panel and returns focus to trigger.
await triggerButton.click();
const panel = page.locator('[role="region"]'); // or your panel selector
await expect(panel.locator('button[aria-label*="Close"]')).toBeFocused();
await page.keyboard.press('Escape');
await page.waitForTimeout(150); // allow React unmount + setTimeout(0)
await expect(triggerButton).toBeFocused();
5. Disclosure Widget
Interactions: Enter/Space toggle aria-expanded between "true"/"false"; aria-controls references the panel id; panel visibility matches expanded state.
const btn = page.locator('button[aria-expanded]');
await btn.focus();
const initial = await btn.getAttribute('aria-expanded');
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
const toggled = await btn.getAttribute('aria-expanded');
expect(toggled).not.toBe(initial);
const panelId = await btn.getAttribute('aria-controls');
const panel = page.locator(`#${panelId}`);
await expect(panel).toBeVisible(); // when expanded=true
6. Menu Button / Dropdown Interactions: Enter/Space opens menu, focus moves to first item; Arrow keys navigate with wrapping; Escape closes and returns focus to trigger; Home/End jump to first/last; type-ahead jumps to matching item.
const trigger = page.locator('button[aria-haspopup="menu"]');
await trigger.focus();
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
const menu = page.locator('[role="menu"]');
await expect(menu).toBeVisible();
await expect(menu.locator('[role="menuitem"]').first()).toBeFocused();
await page.keyboard.press('End');
await expect(menu.locator('[role="menuitem"]').last()).toBeFocused();
await page.keyboard.press('Escape');
await expect(trigger).toBeFocused();
7. Combobox / Autocomplete
Interactions: typing shows listbox with filtered options; ArrowDown focuses first option; Enter selects and closes; Escape closes without selection; aria-expanded and aria-activedescendant update.
const input = page.locator('[role="combobox"]');
await input.focus();
await input.type('ap');
await page.waitForTimeout(300);
await expect(input).toHaveAttribute('aria-expanded', 'true');
const listbox = page.locator('[role="listbox"]');
await page.keyboard.press('ArrowDown');
expect(await input.getAttribute('aria-activedescendant')).toBeTruthy();
await page.keyboard.press('Enter');
await expect(listbox).toBeHidden();
8. Listbox (single and multi-select) Interactions: Arrow keys move selection in single-select; Space toggles in multi-select; Shift+Arrow extends range; Home/End jump to first/last; type-ahead navigation.
const listbox = page.locator('[role="listbox"]');
await listbox.focus();
await expect(listbox.locator('[role="option"]').first()).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(150);
await expect(listbox.locator('[role="option"]').nth(1)).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('End');
await expect(listbox.locator('[role="option"]').last()).toBeFocused();
9. Slider
Interactions: ArrowLeft/Right adjust by step; PageUp/Down by larger increment; Home/End set to min/max; aria-valuenow, aria-valuemin, aria-valuemax update.
const slider = page.locator('[role="slider"]');
await slider.focus();
const before = Number(await slider.getAttribute('aria-valuenow'));
await page.keyboard.press('ArrowRight');
await page.waitForTimeout(150);
expect(Number(await slider.getAttribute('aria-valuenow'))).toBeGreaterThan(before);
await page.keyboard.press('Home');
expect(await slider.getAttribute('aria-valuenow')).toBe(await slider.getAttribute('aria-valuemin'));
await page.keyboard.press('End');
expect(await slider.getAttribute('aria-valuenow')).toBe(await slider.getAttribute('aria-valuemax'));
10. Date Picker Interactions: Arrow keys navigate days; PageUp/Down navigate months; Shift+PageUp/Down navigate years; Enter selects and closes; Escape closes without selection and returns focus to input.
const input = page.locator('[aria-label*="date" i]');
await input.focus();
await page.keyboard.press('Enter');
const grid = page.locator('[role="grid"]');
await expect(grid).toBeVisible();
await page.keyboard.press('ArrowRight');
await page.keyboard.press('PageDown');
await page.keyboard.press('Enter');
await expect(grid).toBeHidden();
expect(await input.inputValue()).not.toBe('');
11. Accordion
Interactions: Enter/Space on header toggles panel; aria-expanded reflects state; Arrow keys move between headers; Home/End jump to first/last header.
const headers = page.locator('[role="button"][aria-expanded]');
await headers.first().focus();
const initial = await headers.first().getAttribute('aria-expanded');
await page.keyboard.press('Enter');
await page.waitForTimeout(200);
expect(await headers.first().getAttribute('aria-expanded')).not.toBe(initial);
await page.keyboard.press('ArrowDown');
await expect(headers.nth(1)).toBeFocused();
await page.keyboard.press('End');
await expect(headers.last()).toBeFocused();
12. Radio Group
Interactions: Arrow keys move selection within group (roving tabindex); Tab moves to/from group as a whole; first or checked radio receives initial focus; aria-checked updates with selection.
const radios = page.locator('[role="radiogroup"] [role="radio"]');
await radios.first().focus();
await page.keyboard.press('ArrowDown');
await page.waitForTimeout(150);
await expect(radios.nth(1)).toHaveAttribute('aria-checked', 'true');
await expect(radios.first()).toHaveAttribute('aria-checked', 'false');
await page.keyboard.press('Tab');
await expect(radios.nth(1)).not.toBeFocused();
Keyboard tests MUST run against a real site (local dev environment like Lando/DDEV, or staging). Guard against accidental use of mocks:
if (!BASE_URL || !BASE_URL.match(/https?:\/\/.+/)) {
throw new Error('Keyboard tests require a real site. Set BASE_URL.');
}
React and other SPA frameworks introduce gotchas that break naive Playwright tests:
No direct URL navigation: SPA routes (e.g., /book/truth-lending/2460032) return 404 from the server — the server has no route for them. Navigate WITHIN the app by clicking menu items and waiting for React to render. Use waitForSelector() to confirm content has loaded before interacting.
Duplicate DOM (mobile + desktop): Many React apps render the same component twice — once for desktop, once for mobile. Playwright strict mode throws when a selector matches both. Fix by scoping to a container (nav.left-sidebar [role="tree"]) or appending .first() / .last() to your locator.
React state waits: After page.keyboard.press(), React state updates are async — the DOM may not reflect the new state for tens of milliseconds. Add waitForTimeout(200–500) or waitForFunction(() => ...) before asserting on ARIA attributes that change via React state.
React 16 setTimeout(0) for focus-after-unmount: In React 16, focus calls issued inside async callbacks do not survive component unmount. Production code must wrap the focus call in setTimeout(() => el.focus(), 0). Tests must account for this by allowing 100–200ms after a panel closes before checking document.activeElement.
DOMPurify stripping data-* attributes: A bare DOMPurify.sanitize() call strips data-* attributes by default. If tests find click handlers broken after sanitization, the fix is to route sanitization through a wrapper component that calls sanitize at render time (not as a pre-processing step that discards needed attributes).
Playwright MCP cannot deliver keyboard events: The Playwright MCP browser integration CANNOT forward keyboard events — browser_press_key calls are silently dropped for most interactive widgets. Always run keyboard a11y tests with npx playwright test using .spec.js files. Use the MCP browser only for visual inspection and DOM queries.
visibility:hidden + :focus-within catch-22 (CRITICAL)
Never use visibility: hidden on elements that are supposed to become visible when a parent receives keyboard focus via :focus-within. The pattern creates an impossible state for keyboard users:
visibility: hidden removes the element from the tab order entirely:focus-within is never triggered on the parent/* ❌ BROKEN — keyboard users can never trigger :focus-within on the parent */
.annotation-block-edit {
opacity: 0;
visibility: hidden; /* removes from tab order → :focus-within never fires */
}
.annotation-block:focus-within .annotation-block-edit {
opacity: 1;
visibility: visible;
}
/* ✅ CORRECT — opacity keeps element in tab order; :focus-within works */
.annotation-block-edit {
opacity: 0; /* visually hidden but still focusable */
}
.annotation-block:hover .annotation-block-edit,
.annotation-block:focus-within .annotation-block-edit {
opacity: 1;
}
This applies to any "reveal on hover/focus" pattern: edit buttons, delete buttons, action menus inside cards. Use opacity only (not visibility) when the element must remain keyboard-reachable.
After verifying keyboard operability, also check:
aria-label or visible textaria-pressed or aria-expandedrole="tablist", role="tab", aria-selectedaria-hidden="true"aria-labelaria-selected="true" per tablistRun these tests when <video>, <audio>, or media player components are present.
<track kind="captions"> exists on every <video> with speech<track> has valid src pointing to caption file| Screen Reader | Browser | Mode |
|---|---|---|
| NVDA | Chrome | Browse mode + Focus mode |
| VoiceOver | Safari (macOS) | Web rotor + standard navigation |
| (Optional) JAWS | Chrome/Edge | Virtual cursor + Forms mode |
<main>, <nav>, <header>, <footer> announced correctly<nav> elements have distinguishing aria-label<h1> presentaria-describedby reads after labelaria-live="polite" announces after current speecharia-live="assertive" interrupts; toast content announced without focus movingVisual regression tests ensure accessibility fixes don't introduce unintended visual changes. Supports Playwright and optionally BackstopJS for side-by-side HTML reports.
npx playwright test --update-snapshots on the current branch to establish baselines, then run tests after further changes to detect regressions.--update-snapshots after any build (React, webpack, etc.) has fully finished. Running it during a concurrent build captures mixed pre/post-build screenshots — some pages reflect old code, some new. The resulting baseline is internally inconsistent and will fail on the next clean run. Wait for the build to complete, then run --update-snapshots, then run the tests.Use toHaveScreenshot() with the correct options:
maxDiffPixelRatio (0 to 1): Maximum ratio of different pixels to total pixels. Use 0.01 (1%) for element screenshots, 0.03 (3%) for full-page screenshots. This is the primary control for flakiness.threshold (0 to 1): Per-pixel color distance tolerance (0 = exact, 1 = any color). Default 0.2 is fine for most cases. This is NOT the overall diff threshold.maxDiffPixels: Absolute count of allowed different pixels. Alternative to maxDiffPixelRatio.// Element screenshot — tight tolerance
await expect(element).toHaveScreenshot('name.png', {
maxDiffPixelRatio: 0.01,
});
// Full-page screenshot — looser for dynamic content
await expect(page).toHaveScreenshot('name.png', {
fullPage: true,
maxDiffPixelRatio: 0.03,
mask: [page.locator('.dynamic-region')],
});
BackstopJS provides an HTML report with side-by-side visual diffs — useful for manual review. It can run alongside Playwright tests.
Setup:
npm install --save-dev backstopjs
Configuration (backstop.json):
scenarioDefaults for shared settings (delay, misMatchThreshold, removeSelectors)"selectors": ["document"] for full-page, or class/tag selectors for elements[type='text']) — they cause parse errors in Puppeteer enginerequireSameDimensions: false for pages with dynamic heightsmisMatchThreshold (15-20%) due to dynamic contentPopup/overlay handling:
Create an onReady.cjs engine script (use .cjs extension if project has "type": "module" in package.json):
const wait = (ms) => new Promise(resolve => setTimeout(resolve, ms));
module.exports = async (page, scenario, vp) => {
await wait(2000);
await page.evaluate(() => {
document.querySelectorAll('dialog, [role="dialog"], .modal, .popup').forEach(el => el.remove());
});
await wait(300);
};
Workflow:
npx backstop reference --config=path/to/backstop.json # Capture baseline
npx backstop test --config=path/to/backstop.json # Compare against baseline
npx backstop approve --config=path/to/backstop.json # Promote test -> reference
npx backstop openReport --config=path/to/backstop.json # View HTML report
CMS pages often contain dynamic elements (timestamps, session blocks, popups). These cause false failures.
mask: [page.locator()], BackstopJS uses removeSelectors or hideSelectors..contextual, .toolbar-tray, .messages, [data-drupal-messages], dialog, [role="dialog"], time/date elements.dismissPopups() helper or BackstopJS onReadyScript.waitForLoadState('networkidle') and a short wait to let JS behaviors settle before capture.color-contrast rule enabled (catches most but not all cases)npx playwright show-report for HTML report with side-by-side diffsnpx backstop openReport for visual comparison dashboardInject axe-core into live pages via Playwright for automated WCAG violation detection. This catches issues that manual review misses (computed contrast through CSS layers, missing ARIA on dynamically rendered content, landmark coverage).
// In a Playwright test file (.spec.js)
const { test, expect } = require('@playwright/test');
const fs = require('fs');
test('axe-core accessibility scan', async ({ page }) => {
await page.goto(BASE_URL);
await page.waitForLoadState('networkidle');
// Inject axe-core
const axeSource = fs.readFileSync(
require.resolve('axe-core/axe.min.js'), 'utf-8'
);
await page.evaluate(axeSource);
// Run audit
const results = await page.evaluate(() =>
axe.run(document, {
runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice']
})
);
// Report violations
const violations = results.violations;
if (violations.length > 0) {
const report = violations.map(v => ({
id: v.id,
impact: v.impact,
description: v.description,
helpUrl: v.helpUrl,
nodes: v.nodes.length
}));
console.log('axe violations:', JSON.stringify(report, null, 2));
}
expect(violations.length).toBe(0);
});
For sites with multiple routes, scan each page variant:
After the axe-core scan, use findings to prioritize manual testing effort:
For large sites, classify pages into template groups and scan one representative per group:
discover phase: list all routes, group by template (list page, detail page, form page, etc.)Report axe-core results alongside keyboard and visual regression results:
## axe-core Scan Results
Pages scanned: [count]
Total violations: [count]
Critical: [n] | Serious: [n] | Moderate: [n] | Minor: [n]
### Violations by Rule
| Rule ID | Impact | Description | Pages | Elements |
|---------|--------|-------------|-------|----------|
| color-contrast | serious | Elements must meet color contrast | 3 | 12 |
This output feeds directly into the a11y-critic's Phase 0 (Consume Test Evidence) — measured violations become hard evidence in the design review.
When a test produces a failing keyboard, axe-core, visual, static-analysis, or manual finding, include an A11y Evidence Finding block for each issue that should be handed to a11y-critic or perspective-audit. Do not emit placeholder contracts for passing checks or clean fixtures.
Use these fields when evidence exists:
### A11y Evidence Finding
finding_id: stable lowercase id, e.g. a11y_form_error_describedby
fingerprint: stable 8-64 char hex hash derived from component/target/rule, not the crawl URL alone
source: test command, test file, axe rule id, agent-browser ref, or observed artifact
wcag_or_apg: WCAG 2.2 criterion or WAI-ARIA APG pattern citation
section_508_fpc_context: Section 508 context only when applicable; Revised Section 508 maps web conformance to WCAG 2.0 Level A/AA
severity: CRITICAL | MAJOR | MINOR | ENHANCEMENT
perspective_alarms: screen_reader_semantic=LOW|MEDIUM|HIGH; keyboard_motor=LOW|MEDIUM|HIGH; etc.
evidence: file:line, DOM excerpt, axe node, screenshot, keyboard trace, or measured value
reproduction_steps: commands or user steps needed to reproduce
expected_behavior: what the user or assistive technology should experience
actual_behavior: what the test observed
trend: new | persistent | worsening | improving | resolved
Guidelines:
perspective-audit.Use when the project uses React, Next.js, Vue, or other JSX/TSX framework. Catches missing alt text, invalid ARIA, and inaccessible element nesting at build time — no running server needed.
# Install as dev dependency
pnpm add -D eslint-plugin-jsx-a11y # or npm/yarn
# Create temporary standalone config (avoids ESLint 9 flat config issues)
cat > eslint.a11y.mjs << 'EOF'
import jsxA11y from "eslint-plugin-jsx-a11y";
import tseslint from "typescript-eslint";
export default [{
files: ["src/**/*.tsx", "src/**/*.jsx"],
plugins: { "jsx-a11y": jsxA11y },
languageOptions: {
parser: tseslint.parser,
parserOptions: { ecmaFeatures: { jsx: true } },
},
rules: { ...jsxA11y.flatConfigs.recommended.rules },
}];
EOF
# Run
npx eslint --config eslint.a11y.mjs src/
# Clean up temp config (keep the plugin installed)
rm eslint.a11y.mjs
Custom component role props, ARIA passed via spread, dynamic content loaded post-render, Next.js <Link> components (render valid anchors at runtime).
Lifecycle integration: These test results feed into a11y-critic reviews. The full a11y lifecycle is: plan → [generate test scripts] → critique plan → revise → implement → test (this skill) → critique implementation → fix → re-test
Webwright script generation fits between "plan" and "critique plan" — use it to generate test scripts from the planner's output before running them. Generated scripts are inputs to the test phase, not a replacement for it.