Automated screen reader and WCAG testing

Interactive testing

Assert what users hear, not just DOM attributes

Static linters catch missing alt attributes, but they can't tell you if a custom combobox traps focus, announces its collapsed state, or reads the active option when a user presses ArrowDown. With a11ied/vitest, you can drive a virtual screen reader directly inside your test suite—with zero browser setup or operating system permissions.

import { describe } from 'vitest';
import { test } from 'a11ied/vitest';

const combobox = test.extend({
   srOptions: { url: 'http://localhost:3000/components/combobox' },
});

describe('combobox component', () => {
   combobox('announces active option and expanded state', ({ sr }) => {
      sr.press('Tab')
         .expect.spoken('combobox, Select country, collapsed')
         .press('ArrowDown')
         .expect.spoken('combobox, Select country, expanded')
         .and.spoken('option, Canada, 1 of 3');
   });
});

Chained commands queue and execute in sequence without littering tests with await boilerplate. The in-process virtual screen reader computes the full ARIA accessibility tree and speech queue in milliseconds, asserting against WCAG 4.1.2 (Name, Role, Value) and 2.4.3 (Focus Order) as fast as standard unit tests.

Building a custom widget from scratch? Query official keyboard shortcuts and expected ARIA attributes from the W3C ARIA Authoring Practices Guide (APG) directly from your terminal:

a1 pattern combobox

Auditing & CI

Full-page audits with actionable remediation

Audit local dev servers or staging URLs directly from your terminal or GitHub Actions with a1 audit. Powered by axe-core, every failure is mapped directly to its official WCAG success criterion, isolated to the offending element, and paired with clear instructions to fix it.

a1 audit http://localhost:3000/checkout --level AA

✗ 2 problems to fix.

1.1.1  Non-text Content  [A]
  button[type="button"] > img
  Fix: Provide an alt attribute or aria-label for the icon button.

3.3.1  Error Identification  [A]
  input#card-number
  Fix: Reference the error message element using aria-describedby.

Need deeper context on a criterion? Query official WCAG requirements, failure scenarios, and test methods without leaving your terminal:

a1 wcag 3.3.1

You can also run a1 inspect to discover which criteria apply to a page before testing (see relevant criteria and test methods).

Agentic workflows

A real feedback loop for AI coding agents

AI coding assistants generate UI components rapidly, but they have no way to verify whether assistive technology actually works with what they write. Without runtime feedback, agents guess at ARIA attributes and frequently introduce accessibility regressions in dynamic interfaces.

a11ied provides a local Model Context Protocol (MCP) server that gives Claude Code, Cursor, Windsurf, and other agents native tools to inspect accessibility trees, drive VoiceOver or NVDA, and verify their own fixes against WCAG criteria.

{
  "mcpServers": {
    "a11ied": {
      "command": "npx",
      "args": ["-y", "a11ied", "mcp"]
    }
  }
}

Give your coding agent tasks that require verifying real interaction, not just inspecting static HTML:

Review the checkout dialog on http://localhost:3000/checkout.
Start a screen reader session, open the modal, and verify:
1. Focus moves to the first field inside the dialog.
2. VoiceOver announces the dialog title and modal role upon opening.
3. Pressing Escape closes the dialog and restores focus to the trigger.

The agent runs keyboard navigation commands, inspects the spoken phrase log, diagnoses failures against WCAG criteria, and iterates on the code until the test passes.

Architecture

Simulation speed vs. real OS fidelity

a11ied provides two distinct execution targets so you can balance instantaneous testing speed in CI with full real-world operating system fidelity:

Virtual screen reader A lightweight, headless JavaScript engine that computes the ARIA accessibility tree and speech queue in memory. Runs in milliseconds in Node.js or Linux CI containers with zero browser windows, system permissions, or audio hardware required. Ideal for component tests, unit suites, and fast pull request checks.

VoiceOver & NVDA Real operating system assistive technologies automated via Guidepup—using AppleScript on macOS for VoiceOver and native accessibility APIs on Windows for NVDA. Ideal for end-to-end integration tests, validating platform-specific speech synthesis, and catching OS quirks before release. See the screen readers guide.

Environment check

Run a1 doctor in your terminal to check which browsers, permissions, and screen readers are configured and ready on your machine.

Where to start

Quickstart

Install the package, check your machine, and run your first virtual screen reader session in under two minutes.

Get started

Component testing

Add screen reader assertions to your Vitest suite with the a11ied/vitest fixture, or use a11ied/test with Jest.

Vitest guide

AI agent setup

Connect the MCP server to Cursor, Claude Code, or Windsurf to give your coding assistant accessibility testing tools.

Agent guide

Interactive demo

Walk through auditing and fixing real accessibility violations on a sample team settings app.

Practice on demo