Run doctor first
a1 doctor checks the browser and each screen reader, and prints the exact
command to fix whatever is missing under Action items. Most of the environment errors
below appear when a command runs before a step doctor reported is fixed.
a1 doctorSee the quickstart for what each check does and setting up VoiceOver or NVDA for the one-time steps each of them needs.
Session errors
✗ Error (missing-session): No active screen reader session. Start one with "a1 sr start".
Every sr command but press, type,
do, and walk needs a session already running. Run
sr start --sr virtual <url> first.
find, goto, wait --for, and
expect exit 4 when nothing matches, so a script can act on it. Run
sr transcript to see every announcement so far. Word order
matters: the simulated screen reader announces the role, then the name, such as
"button, Pay", not "Pay, button".
wait only matches announcements made after it starts. An announcement
the triggering command already printed in its own output came before the wait and
does not match. Check that output directly, or run expect --since
against a checkpoint set before the triggering command. See
assert on the transcript.
Browser errors
✗ Error (browser-unavailable): No usable Chromium-family browser is available for Playwright automation.
Install one: npx playwright install chromium, or install Chrome,
Edge, Brave, or Chromium and a1 will find it. a1 doctor --json lists
every candidate it checked under result.browserAutomation.candidates.
--timeout <ms> bounds how long loading the page may take,
10000 ms by default. A route behind auth or a slow dev server needs a longer
timeout, or --wait-for <css> to wait for a specific element
instead of the page's own load event.
VoiceOver started unexpectedly
sr start and sr walk start VoiceOver on macOS when
--sr is not given and no session is active. If VoiceOver just took over
the screen, run a1 sr stop to end that session, then rerun the command
with --sr virtual. Add that flag to every script
and CI step. See run in CI.
a1 sr stop --json
a1 sr walk http://localhost:3000/checkout --sr virtual --jsonRecording problems
See record a session for the full list:
screen recording permission belongs to the app running a1, not to
a1 itself, the simulated screen reader cannot record, and a recording that
is empty means the session was stopped before the file finished writing.
Empty results
A page with under 10 elements and 50 characters of text adds a warning that a
single-page app may not have mounted. Load the route in a browser first to confirm
it renders before trusting an empty axe or tree result.
The relevant criteria scan in a1 audit reports not-detected
for the same reason: it reads only the HTML the server returned, so content a client
framework adds after load is not detected. See the
limits of the relevant criteria scan.