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.
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.
Write a manual screen-reader test script for this flow:
Screen readers requested: .
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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
use in
npx @hermes-hq/hodios install write-screen-reader-test-plan --target claude-codenpx skills add hermes-hq/hodios-dist --skill write-screen-reader-test-plan -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of AccessibilityAccessibility 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-specialistAudit 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-accessibilityAudit 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-accessibilityBuild 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-widgetBuild 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-accessibilityFix 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