Accessibility Testing

What it is

Accessibility testing checks that people using assistive technology — screen readers, keyboards, switch devices, magnification — can use the interface. The reference standard is WCAG, organised around four principles.

1
  Perceivable  ─ can I take it in?      (alt text, contrast, captions)
2
  Operable     ─ can I drive it?        (keyboard, focus, no traps)
3
  Understandable ─ do I get it?         (labels, errors, consistency)
4
  Robust       ─ does it work with AT?  (semantics, valid ARIA)

Automated tools catch roughly a third of issues. The rest needs a keyboard, a screen reader, and real people.

When to use it / when to avoid it

Use it for

Any user-facing UI, especially forms, navigation and interactive widgets
Every PR: a cheap automated scan (axe) in CI catches regressions
Before release: a manual keyboard and screen-reader pass on key flows
Legal or procurement requirements that mandate WCAG 2.2 AA conformance

Avoid or reduce it when

You rely on an automated scan alone and call it “accessible”
The control has no semantic equivalent (a canvas-only UI) without a fallback
You test only the happy path and skip error states and empty states
You ignore focus order and let the keyboard user get trapped

Frameworks & tools

Tool	Ecosystem	Notes
axe-core	JS/TS, browser	The engine behind many tools; rules tagged by WCAG level
jest-axe	JS/TS tests	Assert no violations in component tests
pa11y	Node CLI	Scriptable page checks, CI-ready
Lighthouse	Chrome	Accessibility score within a broader audit
WAVE	Browser ext / API	Visual overlay of issues on the page
Accessibility Insights	Browser ext	Guided manual checks plus automated
NVDA / VoiceOver	Screen readers	Free, essential for manual testing
HTML validator	Any	A valid document is a robust document

Quick setup

1
npm install -D axe-core @axe-core/playwright jest-axe vitest-axe

1
// in a component test
2
import { axe } from 'vitest-axe';

1
pip install playwright axe-playwright-python

1
go install github.com/fortio/fortio@latest   # generic HTTP probing
2
npm install -g pa11y-ci                       # pa11y for any stack

1
# Selenium WebDriver + axe via a node bridge
2
mvn org.apache.maven.plugins:maven-dependency-plugin:get \
3
  -Dartifact=org.seleniumhq.selenium:selenium-java:4.25.0

1
dotnet add package Selenium.WebDriver
2
# run axe-core from the injected script

Example

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

4
test('home page has no accessibility violations', async ({ page }) => {
5
  await page.goto('/');
6
  const results = await new AxeBuilder({ page })
7
    .withTags(['wcag2a', 'wcag2aa'])
8
    .analyze();
9
  expect(results.violations).toEqual([]);
10
});

1
from axe_playwright_python.sync_playwright import Axe
2
from playwright.sync_api import sync_playwright
3

4
with sync_playwright() as p:
5
    page = p.chromium.launch().new_page()
6
    page.goto("http://localhost:4321/")
7
    results = Axe().run(page)
8
    assert not results.violations

1
pa11y --standard WCAG2AA --reporter json http://localhost:4321/

1
AxeBuilder axe = new AxeBuilder().withTags(Arrays.asList("wcag2a", "wcag2aa"));
2
AxeResults results = axe.analyze(driver);
3
assertTrue(results.getViolations().isEmpty());

1
var axe = new AxeBuilder(driver).WithTags("wcag2a", "wcag2aa");
2
var results = axe.Analyze();
3
Assert.Empty(results.Violations);

Anti-patterns & best practices

Automate the detectable, test the rest by hand. Tools are a floor, not a ceiling.
Use semantic HTML first. A <button> beats a <div role="button"> you must keep patching with ARIA.
Check colour contrast with real values. Many “designed” greys fail 4.5:1.
Test the keyboard-only path. Tab order, visible focus, no traps, skip links.
Give images real alt text. Decorative images take alt=""; icons carrying meaning need a name.
Include people with disabilities. Automated checks plus screen-reader users find what neither finds alone.