12Accessibility (a11y) Testing

12.1 Why a11y testing

15% of users have a disability of some kind. Beyond ethics, accessibility is increasingly a legal requirement (EU Accessibility Act 2025, ADA in US, Section 508). And — usefully for SDETs — accessible markup is also the markup Playwright's role-based locators rely on. Improving a11y improves test stability for free.

12.2 WCAG levels

12.3 axe-core + Playwright

axe-core is the industry-standard a11y engine (used by Lighthouse and many tools). Install the Playwright wrapper:

npm i -D @axe-core/playwright

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

test('home page has no detectable a11y violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

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

If there are violations, the message lists each rule (e.g. color-contrast, label) with the failing nodes and a help URL — actionable, not noise.

12.4 Common rules to gate on

12.5 Scoping the scan

// Only scan a specific component
const results = await new AxeBuilder({ page })
  .include('.product-card')
  .exclude('.third-party-widget')
  .withTags(['wcag2aa'])
  .disableRules(['color-contrast'])  // temporary while a contrast fix is in progress
  .analyze();

12.6 Manual checks the automation can't do

• Keyboard navigation — can a user reach every interactive element with Tab? Order makes sense?
• Focus visibility — does the focus ring show on every focusable element?
• Screen reader pass — VoiceOver / NVDA reads pages sensibly; correct headings, list announcements, form errors
• Cognitive — language plain, time limits avoidable, errors fixable
• Real users — best signal; partner with disability orgs for periodic audits

12.7 Keyboard + focus tests (DIY without axe)

test('tab order goes through every form field', async ({ page }) => {
  await page.goto('/signup');
  await page.keyboard.press('Tab');
  await expect(page.getByLabel('Email')).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(page.getByLabel('Password')).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(page.getByLabel('Confirm password')).toBeFocused();
  await page.keyboard.press('Tab');
  await expect(page.getByRole('button', { name: 'Sign up' })).toBeFocused();
});

test('error message is announced to screen readers', async ({ page }) => {
  await page.goto('/login');
  await page.getByRole('button', { name: 'Sign in' }).click();
  const err = page.getByRole('alert');           // role="alert" = aria-live=assertive
  await expect(err).toBeVisible();
  await expect(err).toHaveText(/email is required/i);
});

12.8 CI gating

// tests/a11y.spec.ts — run as part of regular suite
import AxeBuilder from '@axe-core/playwright';

const PAGES = ['/', '/login', '/signup', '/products', '/cart', '/checkout'];
for (const path of PAGES) {
  test(`a11y · ${path}`, async ({ page }) => {
    await page.goto(path);
    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();
    /* Hard fail on any violation. Or soft-fail and report a count. */
    expect(results.violations, JSON.stringify(results.violations, null, 2)).toEqual([]);
  });
}

12.9 WCAG 2.2 (new since 2.1)

• Focus Not Obscured — sticky headers/footers can hide focused element on scroll
• Focus Appearance — focus indicator must meet contrast + thickness
• Dragging Movements — drag must have single-pointer alternative
• Target Size (Minimum) — touch targets ≥ 24×24 CSS pixels
• Consistent Help — help links in same location across pages
• Accessible Authentication — no cognitive tests required (CAPTCHA exceptions)

12.10 Screen reader basics (NVDA / VoiceOver / JAWS)

• NVDA — free Windows; default Insert key. Test on Firefox/Chrome.
• VoiceOver — built into macOS/iOS. Cmd+F5. Use on Safari for parity with iPhone users.
• JAWS — paid Windows; gold standard for enterprise + government.
• TalkBack — Android.

Keyboard cheat sheet — test in every screen reader:

• H — next heading; 1-6 for level
• K — next link; B — next button; F — next form field
• Tab — next interactive; Shift+Tab — previous
• Esc — close popup
• Arrow keys — read line by line

12.11 ARIA — only when HTML doesn't suffice

12.12 Common WCAG failures & how to test

12.13 Programmatic a11y in CI (full pipeline)

// Page object with built-in scan
import AxeBuilder from '@axe-core/playwright';

export class A11yPage {
  constructor(protected page: any) {}
  async scan(opts: { exclude?: string[]; tags?: string[] } = {}) {
    let b = new AxeBuilder({ page: this.page });
    if (opts.exclude) opts.exclude.forEach(s => b = b.exclude(s));
    b = b.withTags(opts.tags ?? ['wcag2a', 'wcag2aa', 'wcag22aa']);
    const r = await b.analyze();
    return r.violations;
  }
}

// Per-PR baseline gate
import baseline from './a11y-baseline.json';
test('no new a11y violations', async ({ page }) => {
  await page.goto('/');
  const violations = await new A11yPage(page).scan();
  const newViolations = violations.filter(v =>
    !baseline.find((b: any) => b.id === v.id && b.nodes.length >= v.nodes.length)
  );
  expect(newViolations, JSON.stringify(newViolations, null, 2)).toEqual([]);
});

12.14 Beyond axe — manual checks

• Keyboard-only walkthrough — unplug mouse for 5 min
• Screen reader pass on critical flows quarterly
• 200% zoom — content still usable, no horizontal scroll
• Color contrast verify with WebAIM Contrast Checker on each new color
• Reduced motion — set prefers-reduced-motion: reduce; animations should shorten / disappear
• Real user testing with disabled users — best signal; partner with orgs like Fable