hermes

Write a screen-reader test plan

Writes a manual screen-reader test script for a user flow on NVDA, JAWS, VoiceOver or TalkBack, with keystrokes and expected announcements per step. Use before releasing a key flow.

context

Testers new to screen readers tend to Tab through a page and call it done. Real users navigate by headings, landmarks, form fields and lists. They switch between browse and focus modes, swipe through items on mobile, and depend on announcements for anything that changes without focus moving. Exact speech also varies by screen reader, version, browser and verbosity setting. A useful script therefore names the gesture or keystroke for each step and states the expected announcement as its required parts (name, role, state, value) rather than one exact string.

task

Write a manual screen-reader test script for this flow:

Screen readers requested: .

  1. Build the test matrix. Pair each screen reader with the browser or platform it is mainly used with: NVDA with Firefox or Chrome on Windows, JAWS with Chrome or Edge, VoiceOver with Safari on macOS, VoiceOver on iOS with Safari or the app, TalkBack with Chrome or the app on Android. Drop any that do not run on and say so.
  2. Write the setup: the versions to record, default verbosity, the speech viewer or log to turn on (NVDA Speech Viewer, VoiceOver caption panel, TalkBack's developer setting for speech output), and resetting state between runs.
  3. Start with orientation checks before the flow: the page or screen title is announced, the headings outline makes sense (H key or the rotor), landmarks are present and labelled, and the language is announced correctly.
  4. For each step of the flow, write:
  • the action in each screen reader's own terms: NVDA and JAWS keys (H, D or R for landmarks, F for form fields, Tab, Enter, Space, Insert+F7 or Insert+F6 lists), VoiceOver keys (VO+Right Arrow, VO+Space, the rotor) or gestures (swipe right, double-tap, the rotor), and TalkBack gestures (swipe right, double-tap, reading controls);
  • the expected announcement as name, role, state and value, for example "Email, edit text, required, invalid entry";
  • the dynamic behaviour to confirm, such as where focus lands after a dialog opens or closes, a live-region announcement for async results, errors announced and linked to their field, and a loading state that is announced and then cleared;
  • the pass criterion and the WCAG success criterion it maps to.
  1. Add negative checks: every control is reachable with the screen reader's standard navigation, not only by mouse or by touch exploration, decorative images are silent, and hidden content is not read out.
  2. If the flow description leaves out what happens at a step (validation, a success message, a redirect), list it under Coverage gaps instead of inventing behaviour.
constraints
  • Do not claim an exact announcement string unless the flow specifies the label text. Expected speech is the components, in any order the screen reader uses.
  • Keystrokes must be real for the named screen reader. If unsure of one, say so rather than guess.
  • Keep each step to one action, so a failure points to one place.
output format

Setup

| Screen reader | Browser or app | Platform | Settings to record | Then the setup and reset steps.

Test script

For each step: | Step | Action (per screen reader) | Expected announcement | Also check | Pass criterion | WCAG SC | Orientation checks come first.

Defect template

Fields to fill for a failure: step, screen reader and version, browser, actual speech (copied from the log), expected, and severity.

Coverage gaps

Unspecified behaviours and parts of the flow not covered.

1 required value still a placeholder; the assistant will ask for it.

details

kind
Prompt: a task you run by name to get one finished thing back
domain
Software engineering
category
Accessibility
level
Intermediate
made for
QA / test engineer, Frontend engineer, Mobile engineer
risk
read-only
version
v1.0.0 · incubating
reviewed
2026-10-02
works in
Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install write-screen-reader-test-plan --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill write-screen-reader-test-plan -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

pairs well with

All of Accessibility
PersonaAccessibility

Accessibility specialist

Accessibility specialist who builds and reviews with WCAG, the ARIA Authoring Practices and real assistive-technology behaviour in mind, ranking barriers by who is blocked.

accessibility-specialist
PromptAccessibility

Audit a mobile screen for accessibility

Audits an iOS, Android, React Native or Flutter screen for labels, traits, focus order, text scaling, touch targets, contrast and gestures, with platform fixes and a VoiceOver or TalkBack test script.

audit-mobile-accessibility
PromptAccessibility

Audit web accessibility against WCAG 2.2

Audits markup or components against WCAG 2.2 and reports each issue by success criterion with user impact, severity and a concrete code fix. Use before a release or a compliance review.

audit-web-accessibility
PromptAccessibility

Build an accessible ARIA widget

Implements a combobox, tabs, dialog, menu, disclosure, tree or listbox per the ARIA Authoring Practices pattern, using native elements whenever they suffice. Use for custom interactive widgets.

build-aria-widget
PromptAccessibility

Build or fix an accessible form

Builds or repairs a web form with programmatic labels, grouping, autocomplete, helpful error messages and announced validation. Use for sign-up, checkout, settings or any data-entry form.

fix-form-accessibility
PromptAccessibility

Fix keyboard navigation in a component

Finds and fixes keyboard barriers in a UI component (focus order, traps, invisible focus, mouse-only controls) and adds a keyboard test checklist. Use when a widget fails without a mouse.

fix-keyboard-navigation