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:
- Scope: Which pages/flows are in scope? What's explicitly excluded?
- Standard: WCAG 2.2 AA (default) or specific organizational policy?
- Priority: Which components are highest risk (forms, modals, navigation, checkout)?
- Exceptions: Known constraints (legacy markup, third-party widgets)?
- 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.getByRole("button", { name: "Confirm" })).toBeFocused();
await page.keyboard.press("Tab");
await expect(dialog.getByRole("button", { name: "Cancel" })).toBeFocused();
// Escape closes and returns focus to trigger
await page.keyboard.press("Escape");
await expect(dialog).toBeHidden();
await expect(trigger).toBeFocused();
});
Skip Link Validation
test("skip link moves focus to main content", async ({ page }) => {
await page.goto("/");
// First Tab should focus skip link
await page.keyboard.press("Tab");
const skipLink = page.getByRole("link", { name: /skip to (main|content)/i });
await expect(skipLink).toBeFocused();
// Activating skip link moves focus to main
await page.keyboard.press("Enter");
await expect(page.locator('#main, [role="main"]').first()).toBeFocused();
});
POUR Principles Reference
| Principle |
Focus Areas |
Example Tests |
| Perceivable |
Alt text, captions, contrast, structure |
Image alternatives, color contrast ratio |
| Operable |
Keyboard, focus, timing, navigation |
Tab order, focus visibility, skip links |
| Understandable |
Labels, instructions, errors, consistency |
Form labels, error messages, predictable behavior |
| Robust |
Valid HTML, ARIA, name/role/value |
Semantic structure, accessible names |
Axe-Core Tags
Default: wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22a, wcag22aa (WCAG 2.2 AA). Use best-practice for additional checks. See references/axe-tags-reference.md for full tag list.
Exception Handling
When exceptions are unavoidable:
- Scope narrowly - specific component/route only
- Document impact - which WCAG criterion, user impact
- Set expiration - owner + remediation date
- Track ticket - link to remediation issue
// [no] Avoid: Global rule disable
new AxeBuilder({ page }).disableRules(["color-contrast"]);
// [ok] Better: Scoped exclusion with documentation
new AxeBuilder({ page })
.exclude("#third-party-widget") // Known issue: JIRA-1234, fix by Q2
.withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
.analyze();
Troubleshooting
| Problem |
Cause |
Solution |
| Axe finds 0 violations but app fails manual audit |
Automation covers ~30-40% |
Add manual testing checklist |
| False positive on dynamic content |
Content not fully rendered |
Wait for stable state before scan |
| Color contrast fails incorrectly |
Background image/gradient |
Use exclude for known false positives |
| Cannot find element by role |
Missing semantic HTML |
Fix markup - this is a real bug |
| Focus not visible |
Missing :focus styles |
Add visible focus indicator CSS |
| Dialog focus not trapped |
Missing focus trap logic |
Implement focus trap (see snippets) |
| Skip link doesn't work |
Target missing tabindex="-1" |
Add tabindex to main content |
CLI Quick Reference
| Command |
Description |
npx playwright test --grep "a11y" |
Run accessibility tests only |
npx playwright test --headed |
Run with visible browser for debugging |
npx playwright test --debug |
Step through with Inspector |
PWDEBUG=1 npx playwright test |
Debug mode with pause |
Red Flags
- Treating a clean axe scan as full WCAG conformance — automation covers only ~30-40% of criteria.
- Globally disabling rules (e.g.,
color-contrast) instead of scoped .exclude() with a documented ticket.
- Scanning before the page reaches a stable state — async content yields false "0 violations".
- Skipping keyboard/focus tests because axe passed — focus order and traps need explicit tests.
References
| Document |
Content |
| Snippets: Setup & Scanning |
axe-core setup, helper, and scanning patterns |
| Snippets: Keyboard, Focus, Semantic |
Keyboard navigation, focus management, semantic structure |
| Snippets: Visual, Names, Checklist |
Visual accessibility, accessible names, critical pages |
| WCAG 2.2 AA Checklist |
Manual audit checklist by POUR principle |
| ARIA Patterns: Widgets Part 1 |
Fundamentals, dialog, tabs, menu widgets |
| ARIA Patterns: Widgets Part 2 |
Accordion, combobox, live regions, tooltip |
| ARIA Patterns: Mistakes & Reference |
Common ARIA mistakes and roles quick reference |
External Resources
Verification
1---
2name: a11y-playwright-testing
3description: '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.'
4license: 'Complete terms in LICENSE.txt'
5metadata:
6 source: https://skillmd.com/skills/gabrielmoreira/a11y-playwright-testing
7---
8
9# Playwright Accessibility Testing (TypeScript)
10
11Comprehensive 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.
12
13> **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.
14
15## When to Use This Skill
16
17- **Automated a11y scans** with axe-core for WCAG 2.2 AA compliance
18- **Keyboard navigation tests** for Tab/Enter/Space/Escape/Arrow key operability
19- **Focus management** validation for dialogs, menus, and dynamic content
20- **Semantic structure** assertions for landmarks, headings, and ARIA
21- **Form accessibility** testing for labels, errors, and instructions
22- **Color contrast** and visual accessibility verification
23- **Screen reader** compatibility testing patterns
24
25### Do NOT Use For
26
27- Selenium/Java accessibility testing (use `accessibility-selenium-testing`).
28- Authoring Playwright functional/UI E2E specs (use `playwright-e2e-testing`).
29- Full conformance sign-off — automated axe scans catch ~30-40% of issues; manual audit + assistive-tech testing is still required.
30
31## Prerequisites
32
33| Requirement | Details |
34| ----------- | ------------------------------ |
35| Node.js | v18+ recommended |
36| Playwright | `@playwright/test` installed |
37| axe-core | `@axe-core/playwright` package |
38| TypeScript | Configured in project |
39
40### Quick Setup
41
42```bash
43# Add axe-core to existing Playwright project
44npm install -D @axe-core/playwright axe-core
45```
46
47## First Questions to Ask
48
49Before writing accessibility tests, clarify:
50
511. **Scope**: Which pages/flows are in scope? What's explicitly excluded?
522. **Standard**: WCAG 2.2 AA (default) or specific organizational policy?
533. **Priority**: Which components are highest risk (forms, modals, navigation, checkout)?
544. **Exceptions**: Known constraints (legacy markup, third-party widgets)?
555. **Assistive Tech**: Which screen readers/browsers need manual testing?
56
57---
58
59## Core Principles
60
61### 1. Automation Limitations
62
63> [!] **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.
64
65### 2. Semantic HTML First
66
67Prefer native HTML semantics over ARIA. Use ARIA only when native elements cannot achieve the required semantics.
68
69```typescript
70// [ok] Semantic HTML - inherently accessible
71await page.getByRole("button", { name: "Submit" }).click();
72
73// [no] ARIA override - requires manual keyboard/focus handling
74await page.locator('[role="button"]').click(); // Often a <div>
75```
76
77### 3. Locator Strategy as A11y Signal
78
79If you **cannot locate an element by role or label**, it's often an accessibility defect.
80
81| Locator Success | Accessibility Signal |
82| -------------------------------------------- | -------------------------- |
83| `getByRole('button', { name: 'Submit' })` [ok] | Button has accessible name |
84| `getByLabel('Email')` [ok] | Input properly labeled |
85| `getByRole('navigation')` [ok] | Landmark exists |
86| `locator('.submit-btn')` [!] | May lack accessible name |
87
88---
89
90## Key Workflows
91
92### Automated Axe Scan (WCAG 2.2 AA)
93
94```typescript
95import AxeBuilder from "@axe-core/playwright";
96import { test, expect } from "@playwright/test";
97
98test("page has no WCAG 2.2 AA violations", async ({ page }) => {
99 await page.goto("/");
100
101 const results = await new AxeBuilder({ page })
102 .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
103 .analyze();
104
105 expect(results.violations).toEqual([]);
106});
107```
108
109### Scoped Axe Scan (Component-Level)
110
111```typescript
112test("form component is accessible", async ({ page }) => {
113 await page.goto("/contact");
114
115 const results = await new AxeBuilder({ page })
116 .include("#contact-form") // Scope to specific component
117 .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
118 .analyze();
119
120 expect(results.violations).toEqual([]);
121});
122```
123
124### Keyboard Navigation Test
125
126```typescript
127test("form is keyboard navigable", async ({ page }) => {
128 await page.goto("/login");
129
130 // Tab to first field
131 await page.keyboard.press("Tab");
132 await expect(page.getByLabel("Email")).toBeFocused();
133
134 // Tab to password
135 await page.keyboard.press("Tab");
136 await expect(page.getByLabel("Password")).toBeFocused();
137
138 // Tab to submit button
139 await page.keyboard.press("Tab");
140 await expect(page.getByRole("button", { name: "Sign in" })).toBeFocused();
141
142 // Submit with Enter
143 await page.keyboard.press("Enter");
144 await expect(page).toHaveURL(/dashboard/);
145});
146```
147
148### Dialog Focus Management
149
150```typescript
151test("dialog traps and returns focus", async ({ page }) => {
152 await page.goto("/settings");
153 const trigger = page.getByRole("button", { name: "Delete account" });
154
155 // Open dialog
156 await trigger.click();
157 const dialog = page.getByRole("dialog");
158 await expect(dialog).toBeVisible();
159
160 // Focus should be inside dialog
161 await expect(dialog.getByRole("button", { name: "Cancel" })).toBeFocused();
162
163 // Tab should stay trapped in dialog
164 await page.keyboard.press("Tab");
165 await expect(dialog.getByRole("button", { name: "Confirm" })).toBeFocused();
166 await page.keyboard.press("Tab");
167 await expect(dialog.getByRole("button", { name: "Cancel" })).toBeFocused();
168
169 // Escape closes and returns focus to trigger
170 await page.keyboard.press("Escape");
171 await expect(dialog).toBeHidden();
172 await expect(trigger).toBeFocused();
173});
174```
175
176### Skip Link Validation
177
178```typescript
179test("skip link moves focus to main content", async ({ page }) => {
180 await page.goto("/");
181
182 // First Tab should focus skip link
183 await page.keyboard.press("Tab");
184 const skipLink = page.getByRole("link", { name: /skip to (main|content)/i });
185 await expect(skipLink).toBeFocused();
186
187 // Activating skip link moves focus to main
188 await page.keyboard.press("Enter");
189 await expect(page.locator('#main, [role="main"]').first()).toBeFocused();
190});
191```
192
193---
194
195## POUR Principles Reference
196
197| Principle | Focus Areas | Example Tests |
198| ------------------ | ----------------------------------------- | ------------------------------------------------- |
199| **Perceivable** | Alt text, captions, contrast, structure | Image alternatives, color contrast ratio |
200| **Operable** | Keyboard, focus, timing, navigation | Tab order, focus visibility, skip links |
201| **Understandable** | Labels, instructions, errors, consistency | Form labels, error messages, predictable behavior |
202| **Robust** | Valid HTML, ARIA, name/role/value | Semantic structure, accessible names |
203
204---
205
206## Axe-Core Tags
207
208Default: `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22a`, `wcag22aa` (WCAG 2.2 AA). Use `best-practice` for additional checks. See [`references/axe-tags-reference.md`](references/axe-tags-reference.md) for full tag list.
209
210---
211
212## Exception Handling
213
214When exceptions are unavoidable:
215
2161. **Scope narrowly** - specific component/route only
2172. **Document impact** - which WCAG criterion, user impact
2183. **Set expiration** - owner + remediation date
2194. **Track ticket** - link to remediation issue
220
221```typescript
222// [no] Avoid: Global rule disable
223new AxeBuilder({ page }).disableRules(["color-contrast"]);
224
225// [ok] Better: Scoped exclusion with documentation
226new AxeBuilder({ page })
227 .exclude("#third-party-widget") // Known issue: JIRA-1234, fix by Q2
228 .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22a", "wcag22aa"])
229 .analyze();
230```
231
232---
233
234## Troubleshooting
235
236| Problem | Cause | Solution |
237| ------------------------------------------------- | ------------------------------ | --------------------------------------- |
238| Axe finds 0 violations but app fails manual audit | Automation covers ~30-40% | Add manual testing checklist |
239| False positive on dynamic content | Content not fully rendered | Wait for stable state before scan |
240| Color contrast fails incorrectly | Background image/gradient | Use `exclude` for known false positives |
241| Cannot find element by role | Missing semantic HTML | Fix markup - this is a real bug |
242| Focus not visible | Missing `:focus` styles | Add visible focus indicator CSS |
243| Dialog focus not trapped | Missing focus trap logic | Implement focus trap (see snippets) |
244| Skip link doesn't work | Target missing `tabindex="-1"` | Add tabindex to main content |
245
246---
247
248## CLI Quick Reference
249
250| Command | Description |
251| ----------------------------------- | -------------------------------------- |
252| `npx playwright test --grep "a11y"` | Run accessibility tests only |
253| `npx playwright test --headed` | Run with visible browser for debugging |
254| `npx playwright test --debug` | Step through with Inspector |
255| `PWDEBUG=1 npx playwright test` | Debug mode with pause |
256
257---
258
259## Red Flags
260
261- Treating a clean axe scan as full WCAG conformance — automation covers only ~30-40% of criteria.
262- Globally disabling rules (e.g., `color-contrast`) instead of scoped `.exclude()` with a documented ticket.
263- Scanning before the page reaches a stable state — async content yields false "0 violations".
264- Skipping keyboard/focus tests because axe passed — focus order and traps need explicit tests.
265
266---
267
268## References
269
270| Document | Content |
271| -------------------------------------------------------------------------------- | ------------------------------------------------ |
272| [Snippets: Setup & Scanning](./references/snippets-setup-and-scanning.md) | axe-core setup, helper, and scanning patterns |
273| [Snippets: Keyboard, Focus, Semantic](./references/snippets-keyboard-focus-semantic.md) | Keyboard navigation, focus management, semantic structure |
274| [Snippets: Visual, Names, Checklist](./references/snippets-visual-names-checklist.md) | Visual accessibility, accessible names, critical pages |
275| [WCAG 2.2 AA Checklist](./references/wcag21aa-checklist.md) | Manual audit checklist by POUR principle |
276| [ARIA Patterns: Widgets Part 1](./references/aria-patterns-widgets-1.md) | Fundamentals, dialog, tabs, menu widgets |
277| [ARIA Patterns: Widgets Part 2](./references/aria-patterns-widgets-2.md) | Accordion, combobox, live regions, tooltip |
278| [ARIA Patterns: Mistakes & Reference](./references/aria-patterns-mistakes.md) | Common ARIA mistakes and roles quick reference |
279
280## External Resources
281
282| Resource | URL |
283| ---------------------------- | --------------------------------------- |
284| WCAG 2.2 Specification | https://www.w3.org/TR/WCAG22/ |
285| WCAG Quick Reference | https://www.w3.org/WAI/WCAG22/quickref/ |
286| WAI-ARIA Authoring Practices | https://www.w3.org/WAI/ARIA/apg/ |
287| axe-core Rules | https://dequeuniversity.com/rules/axe/ |
288
289---
290
291## Verification
292
293- [ ] **axe-core audit passes** — `AxeBuilder.analyze()` returns zero critical violations
294- [ ] **Keyboard navigation tested** — All interactive elements reachable via Tab; focus order is logical
295- [ ] **Color contrast sufficient** — WCAG 2.2 AA minimum contrast ratios met (4.5:1 normal text, 3:1 large text)
296- [ ] **WCAG 2.2 AA conformance** — Tags `wcag22a`/`wcag22aa` included in scans (focus-not-obscured, dragging movements, target-size minimums)