a11ied

Docs

Browse docs
Accessibility test toolkit

Screen readers

Automated accessibility testing requires different trade-offs at different stages of development. a11ied provides three execution targets: a zero-setup virtual screen reader for instant in-process assertions, and real automation for VoiceOver on macOS and NVDA on Windows.

Pass --sr <target> to select an engine, and inspect detailed runtime metadata on every response.

Target matrix

Supported screen reader engines

virtual Headless & In-process (Cross-platform). A complete software screen reader engine that computes the ARIA accessibility tree and announcement sequence in memory or headless Chromium. Requires zero system permissions, operates identically across macOS, Windows, and Linux, and executes in milliseconds inside unit tests or CI pipelines.
voiceover macOS Native Assistive Technology. Automates Apple's built-in VoiceOver through AppleScript and Guidepup. Interacts with the real operating system accessibility API and can record synchronized video to .mov files.
nvda Windows Open-Source Assistive Technology. Automates the NVDA screen reader on Windows through Guidepup and native platform hooks. Captures spoken speech output and supports .mp4 screen recording.

Every response from an a1 sr command includes precise provenance metadata:

  • target: The requested engine (virtual, voiceover, or nvda).
  • targetType: real for native OS screen readers or simulated for virtual mode.
  • engine: For virtual sessions, reports browser (headless Chromium running live client JavaScript) or jsdom (in-memory DOM).

Automation defaults

Target selection & fallback hierarchy

When you invoke a1 sr start without specifying an explicit --sr flag, a11ied intelligently selects the appropriate target based on your current operating system and environment readiness:

  1. Platform detection: On macOS, it defaults to voiceover. On Windows, it defaults to nvda. On Linux, CI containers, and Docker environments, it defaults to virtual.
  2. Readiness check: If native VoiceOver or NVDA is detected but a1 doctor reports that required system permissions or preference bundles are missing (requires-setup), the session automatically falls back to virtual.
  3. Transparent notice: When a fallback occurs, a11ied emits a clear warning in the output stating that a virtual simulation ran rather than native assistive technology, along with the a1 doctor command to configure native support.

Headless simulation

Virtual screen reader

The virtual screen reader is engineered for maximum speed and deterministic reproducibility. Because native screen readers take control of system focus and audio, running them in automated watch loops or shared CI workers is often impractical.

When starting a virtual session explicitly on macOS or Windows, pass --sr virtual: 

a1 sr start --sr virtual http://localhost:3000/checkout

Execution modes:

  • Browser engine (Default for URLs): When passed an HTTP/HTTPS URL, the virtual reader spins up a headless Chromium instance. All client-side JavaScript, custom elements, CSS transitions, and dynamic DOM mutations (such as modal popups and live status updates) execute exactly as they do in production.
  • JSDOM engine (In-memory testing): When testing raw HTML strings or running isolated unit tests without a local web server, the virtual reader operates in-memory using jsdom for sub-millisecond execution.
AI agent friendly

Because the virtual engine requires no audio hardware and produces structured JSON logs, it is the primary target used by AI coding assistants via the Model Context Protocol (MCP) server.

Operating system fidelity

Real OS screen readers (VoiceOver & NVDA)

Real screen readers interact directly with the operating system's accessibility tree and speech synthesizer. When you start a session targeting voiceover or nvda, a11ied launches your system browser, brings its window to the foreground, and attaches Guidepup automation: 

a1 sr start --sr voiceover http://localhost:3000/checkout
a1 sr next

Window management: If you switch windows while inspecting tests, run a1 sr focus to restore the test browser to the foreground. You can also target specific processes using --app, --bundle-id, --process, or --window-title.

One-time machine setup: Before running native screen readers for the first time, run a1 setup to install necessary preference bundles and verify OS permissions: 

a1 setup

On macOS, this enables AppleScript control within VoiceOver settings and installs the Guidepup testing preferences bundle. To record video demonstrations of tests in action, grant Screen Recording permissions to your terminal or host app in macOS System Settings. See the recording guide.

VoiceOver command sets: When controlling VoiceOver, a11ied defaults to semantic VoiceOver Commander commands (direct AppleScript IPC, layout-independent, fast and deterministic), while also supporting physical VoiceOver Keycodes (OS-level simulated modifier chords). See the VoiceOver Commander vs. Keycodes guide for an in-depth comparison.

Architecture guide

Choosing the right target

Use virtual when: You are writing unit or component tests with a11ied/vitest; running pull request validation in Linux CI/CD pipelines; running fast TDD watch loops during development; or connecting AI coding agents via MCP. Virtual testing is instantaneous, headless, and identical across developer machines.
Use VoiceOver or NVDA when: You need to verify platform-specific accessibility quirks; test keyboard rotor or elements list navigation; confirm cursor placement across complex OS dialog transitions; create video evidence for QA or compliance audits; or investigate bug reports originating from real assistive technology users.
a11ied / open source accessibility testingaxe + VoiceOver + NVDA / CLI + TypeScript + MCP