1# Accessibility Testing
2 
3## Table of Contents
4 
51. [Axe-Core Integration](#axe-core-integration)
62. [Keyboard Navigation](#keyboard-navigation)
73. [ARIA Validation](#aria-validation)
84. [Focus Management](#focus-management)
95. [Color & Contrast](#color--contrast)
10 
11## Axe-Core Integration
12 
13### Setup
14 
15```bash
16npm install -D @axe-core/playwright
17```
18 
19### Basic A11y Test
20 
21```typescript
22import { test, expect } from "@playwright/test";
23import AxeBuilder from "@axe-core/playwright";
24 
25test("homepage should have no a11y violations", async ({ page }) => {
26  await page.goto("/");
27 
28  const results = await new AxeBuilder({ page }).analyze();
29 
30  expect(results.violations).toEqual([]);
31});
32```
33 
34### Scoped Analysis
35 
36```typescript
37test("form accessibility", async ({ page }) => {
38  await page.goto("/contact");
39 
40  // Analyze only the form
41  const results = await new AxeBuilder({ page })
42    .include("#contact-form")
43    .analyze();
44 
45  expect(results.violations).toEqual([]);
46});
47 
48test("ignore known issues", async ({ page }) => {
49  await page.goto("/legacy-page");
50 
51  const results = await new AxeBuilder({ page })
52    .exclude(".legacy-widget") // Skip legacy component
53    .disableRules(["color-contrast"]) // Disable specific rule
54    .analyze();
55 
56  expect(results.violations).toEqual([]);
57});
58```
59 
60### A11y Fixture
61 
62```typescript
63// fixtures/a11y.fixture.ts
64import { test as base } from "@playwright/test";
65import AxeBuilder from "@axe-core/playwright";
66 
67type A11yFixtures = {
68  makeAxeBuilder: () => AxeBuilder;
69};
70 
71export const test = base.extend<A11yFixtures>({
72  makeAxeBuilder: async ({ page }, use) => {
73    await use(() =>
74      new AxeBuilder({ page }).withTags([
75        "wcag2a",
76        "wcag2aa",
77        "wcag21a",
78        "wcag21aa",
79      ]),
80    );
81  },
82});
83 
84// Usage
85test("dashboard a11y", async ({ page, makeAxeBuilder }) => {
86  await page.goto("/dashboard");
87  const results = await makeAxeBuilder().analyze();
88  expect(results.violations).toEqual([]);
89});
90```
91 
92### Detailed Violation Reporting
93 
94```typescript
95test("report a11y issues", async ({ page }) => {
96  await page.goto("/");
97 
98  const results = await new AxeBuilder({ page }).analyze();
99 
100  // Custom failure message with details
101  const violations = results.violations.map((v) => ({
102    id: v.id,
103    impact: v.impact,
104    description: v.description,
105    nodes: v.nodes.map((n) => n.html),
106  }));
107 
108  expect(violations, JSON.stringify(violations, null, 2)).toHaveLength(0);
109});
110```
111 
112## Keyboard Navigation
113 
114### Tab Order Testing
115 
116```typescript
117test("correct tab order in form", async ({ page }) => {
118  await page.goto("/signup");
119 
120  // Start from the beginning
121  await page.keyboard.press("Tab");
122  await expect(page.getByLabel("Email")).toBeFocused();
123 
124  await page.keyboard.press("Tab");
125  await expect(page.getByLabel("Password")).toBeFocused();
126 
127  await page.keyboard.press("Tab");
128  await expect(page.getByRole("button", { name: "Sign up" })).toBeFocused();
129});
130```
131 
132### Keyboard-Only Interaction
133 
134```typescript
135test("complete flow with keyboard only", async ({ page }) => {
136  await page.goto("/products");
137 
138  // Navigate to product with keyboard
139  await page.keyboard.press("Tab"); // Skip to main content
140  await page.keyboard.press("Tab"); // First product
141  await page.keyboard.press("Enter"); // Open product
142 
143  await expect(page).toHaveURL(/\/products\/\d+/);
144 
145  // Add to cart with keyboard
146  await page.keyboard.press("Tab");
147  await page.keyboard.press("Tab"); // Navigate to "Add to Cart"
148  await page.keyboard.press("Enter");
149 
150  await expect(page.getByRole("alert")).toContainText("Added to cart");
151});
152```
153 
154### Skip Links
155 
156```typescript
157test("skip link works", async ({ page }) => {
158  await page.goto("/");
159 
160  await page.keyboard.press("Tab");
161  const skipLink = page.getByRole("link", { name: /skip to main/i });
162  await expect(skipLink).toBeFocused();
163 
164  await page.keyboard.press("Enter");
165 
166  // Focus should move to main content
167  await expect(page.getByRole("main")).toBeFocused();
168});
169```
170 
171### Escape Key Handling
172 
173```typescript
174test("escape closes modal", async ({ page }) => {
175  await page.goto("/dashboard");
176  await page.getByRole("button", { name: "Settings" }).click();
177 
178  const modal = page.getByRole("dialog");
179  await expect(modal).toBeVisible();
180 
181  await page.keyboard.press("Escape");
182 
183  await expect(modal).toBeHidden();
184  // Focus should return to trigger
185  await expect(page.getByRole("button", { name: "Settings" })).toBeFocused();
186});
187```
188 
189## ARIA Validation
190 
191### Role Verification
192 
193```typescript
194test("correct ARIA roles", async ({ page }) => {
195  await page.goto("/dashboard");
196 
197  // Verify landmark roles
198  await expect(page.getByRole("navigation")).toBeVisible();
199  await expect(page.getByRole("main")).toBeVisible();
200  await expect(page.getByRole("contentinfo")).toBeVisible(); // footer
201 
202  // Verify interactive roles
203  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
204  await expect(page.getByRole("search")).toBeVisible();
205});
206```
207 
208### ARIA States
209 
210```typescript
211test("aria-expanded updates correctly", async ({ page }) => {
212  await page.goto("/faq");
213 
214  const accordion = page.getByRole("button", { name: "Shipping" });
215 
216  // Initially collapsed
217  await expect(accordion).toHaveAttribute("aria-expanded", "false");
218 
219  await accordion.click();
220 
221  // Now expanded
222  await expect(accordion).toHaveAttribute("aria-expanded", "true");
223 
224  // Content is visible
225  const panel = page.getByRole("region", { name: "Shipping" });
226  await expect(panel).toBeVisible();
227});
228```
229 
230### Live Regions
231 
232```typescript
233test("live region announces updates", async ({ page }) => {
234  await page.goto("/checkout");
235 
236  // Find live region
237  const liveRegion = page.locator('[aria-live="polite"]');
238 
239  await page.getByLabel("Quantity").fill("3");
240 
241  // Live region should update with new total
242  await expect(liveRegion).toContainText("Total: $29.97");
243});
244```
245 
246## Focus Management
247 
248### Focus Trap in Modal
249 
250```typescript
251test("focus trapped in modal", async ({ page }) => {
252  await page.goto("/");
253  await page.getByRole("button", { name: "Open Modal" }).click();
254 
255  const modal = page.getByRole("dialog");
256  await expect(modal).toBeVisible();
257 
258  // Get all focusable elements in modal
259  const focusableElements = modal.locator(
260    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
261  );
262  const count = await focusableElements.count();
263 
264  // Tab through all elements, should stay in modal
265  for (let i = 0; i < count + 1; i++) {
266    await page.keyboard.press("Tab");
267    const focused = page.locator(":focus");
268    await expect(modal).toContainText((await focused.textContent()) || "");
269  }
270});
271```
272 
273### Focus Restoration
274 
275```typescript
276test("focus returns after modal close", async ({ page }) => {
277  await page.goto("/");
278 
279  const trigger = page.getByRole("button", { name: "Delete Item" });
280  await trigger.click();
281 
282  await page.getByRole("button", { name: "Cancel" }).click();
283 
284  // Focus should return to the trigger
285  await expect(trigger).toBeFocused();
286});
287```
288 
289## Color & Contrast
290 
291### High Contrast Mode
292 
293```typescript
294test("works in high contrast mode", async ({ page }) => {
295  await page.emulateMedia({ forcedColors: "active" });
296  await page.goto("/");
297 
298  // Verify key elements are visible
299  await expect(page.getByRole("navigation")).toBeVisible();
300  await expect(page.getByRole("button", { name: "Sign In" })).toBeVisible();
301 
302  // Take screenshot for visual verification
303  await expect(page).toHaveScreenshot("high-contrast.png");
304});
305```
306 
307### Reduced Motion
308 
309```typescript
310test("respects reduced motion preference", async ({ page }) => {
311  await page.emulateMedia({ reducedMotion: "reduce" });
312  await page.goto("/");
313 
314  // Animations should be disabled
315  const hero = page.getByTestId("hero-animation");
316  const animation = await hero.evaluate(
317    (el) => getComputedStyle(el).animationDuration,
318  );
319 
320  expect(animation).toBe("0s");
321});
322```
323 
324## CI Integration
325 
326### A11y as CI Gate
327 
328```typescript
329// playwright.config.ts
330export default defineConfig({
331  projects: [
332    {
333      name: "a11y",
334      testMatch: /.*\.a11y\.spec\.ts/,
335      use: { ...devices["Desktop Chrome"] },
336    },
337  ],
338});
339```
340 
341```yaml
342# .github/workflows/a11y.yml
343- name: Run accessibility tests
344  run: npx playwright test --project=a11y
345```
346 
347## Anti-Patterns to Avoid
348 
349| Anti-Pattern                  | Problem                      | Solution                                   |
350| ----------------------------- | ---------------------------- | ------------------------------------------ |
351| Testing a11y only on homepage | Misses issues on other pages | Test all critical user flows               |
352| Ignoring all violations       | No value from tests          | Address or explicitly exclude known issues |
353| Only automated testing        | Misses many a11y issues      | Combine with manual testing                |
354| Testing without screen reader | Misses interaction issues    | Test with VoiceOver/NVDA periodically      |
355 
356## Related References
357 
358- **Locators**: See [locators.md](../core/locators.md) for role-based selectors
359- **Visual testing**: See [test-suite-structure.md](../core/test-suite-structure.md) for screenshot comparison
360