screen-reader-test-plan
Skill0 starsChanged 29 days agoMITView on GitHub
Use when asked to test a page or flow with a screen reader, when writing an accessibility test script, or when reading order and focus order cannot be judged from the markup alone.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-authenticationSkill
- accessible-formsSkill
- accessible-nameSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- combobox-autocompleteSkill
- data-tableSkill
- email-html-accessibilitySkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Test with the keyboard alone first.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Screen reader test plan
Criteria: SC 4.1.2 Name, Role, Value, SC 1.3.1 Info and Relationships, SC 4.1.3 Status Messages, SC 2.4.3 Focus Order
A screen reader presents a page as a flat, linear stream of announcements with no visual layout. That single fact drives the whole test: reading order and browse mode matter more than anything a screenshot shows. Record the expected announcement at each step, then compare it with what you actually hear — "it read fine" is not a result.
Test with the keyboard alone first. A screen reader is not a substitute for keyboard testing, and a passing keyboard test does not mean the announcements are correct.
When to use
- "Test this with VoiceOver / NVDA / JAWS."
- Writing or reviewing a QA script, a test plan, or an acceptance checklist.
- A ticket says "screen reader users cannot use this form or widget."
- Reading order or focus order cannot be decided by reading the markup.
Procedure
- Pick your setup and write it down. One reader, one browser, exact versions, for example NVDA with Firefox, or VoiceOver with Safari. One reader is a sample, not proof of conformance across all of them.
Run the ordered script below. For each step, write the expected announcement before you listen, so a mismatch is visible rather than absorbed. The criteria in the last column are what the step proves.
# Do this Expected announcement Criterion 1 Load the page and stop at the start the document title, then the page landmark: "banner" SC 1.3.1 2 Move to the top (Ctrl+Home, or VO+Home) and read forward in browse mode landmarks by name — "banner", "navigation", "main"; each heading as "heading level 1, Checkout"; lists as "list, 4 items"; tables as "table, 3 columns, 4 rows" with header cells SC 1.3.1 3 Jump by heading ( Hin NVDA/JAWS, VO+Cmd+H in VoiceOver)the outline is logical and no level is skipped SC 1.3.1 4 Jump by landmark ( D, or the rotor)exactly one "main", a named "navigation" SC 1.3.1 5 Leave browse mode and Tab through every control each control gives role, name and state: "Sign in, button", "Email, edit, required", "Remember me, checkbox, not checked" SC 4.1.2, SC 2.4.3 6 Tab through again and watch the order the sequence follows the visual and logical order, with no jump backwards SC 2.4.3 7 Operate each control with Enter, Space and the arrow keys the state changes are announced: "expanded", "checked", "selected" SC 4.1.2 8 Submit the form with invalid data the error is announced and the field reports "invalid entry" SC 4.1.2 9 Trigger an async update (save, filter, result count) the status is announced without focus moving SC 4.1.3 10 Open a dialog focus moves inside and the dialog name is announced: "Sign in, dialog"; Escape closes it and focus returns to the trigger SC 2.4.3, SC 4.1.2 - Give browse mode and reading order their own attention. Browse mode is the virtual cursor with which a screen reader user skims content; if something is not reachable in browse mode, it is effectively invisible. Focus mode is where keystrokes go to the page so a control can be typed into. Both must work — a custom widget that never triggers focus mode cannot be typed into, and one that never returns to browse mode traps the user.
- Match the flat order to the intended order. Because the reader presents the DOM linearly, positioned and reordered content is read in source order, not visual order. Compare the announcement sequence with the layout and fix the DOM, not the CSS.
Log the result as a transcript, expected against actual, including version and browser, so someone else can reproduce it.
# /checkout — NVDA 2024.4 with Firefox (expected announcement) [load] "Checkout — Example, page" [browse] "banner" [browse] "navigation, Main" [browse] "main" [browse] "heading level 1, Checkout" [Tab] "Full name, edit, required" [Tab] "Card number, edit, has popup collapsed" [submit] "There is 1 error" # error summary, announced [after save] "Order placed" # role=status regionProvide the status region the script expects (SC 4.1.3). A saved message must reach the user without stealing focus:
<!-- The announcement at step 9 comes from a live region, not a focus move. --> <p id="cart-status" role="status"></p>
Verify
The verify step is the recording itself. A step passes only when the actual announcement matches the expected one written before the test.
PASS: heard "Search, button"
FAIL: heard "button" -> no accessible name (SC 4.1.2)
FAIL: heard nothing -> element not in the accessibility tree (SC 1.3.1)Flags that must count as failures, not near-misses:
- "unlabelled", "no name", or a bare role with nothing after it.
- "clickable" on something that is not a button or link, or a link announced as a button.
- A heading level that jumps from 1 to 3.
- A status change that is never announced (SC 4.1.3).
- Focus that moves somewhere different from the visual order (SC 2.4.3).
Failure modes
- Testing in browse mode only. The reader skims the page and everything sounds fine, but the control cannot be typed into because focus mode is never entered.
- Reading the DevTools accessibility tree instead of listening. The tree shows the computed name and role; it does not show that a live region is never announced or that the reading order is confusing.
- Recording "it read fine". Without the expected announcement written down first, there is nothing to compare against and nothing to reproduce.
- Declaring conformance from one screen reader. NVDA, JAWS, VoiceOver and TalkBack differ in what they announce; a single pass is a sample.
- Skipping state and value changes. A toggle that never says "expanded" or a slider that never announces its value passes a role-and-name check and fails the user.
- Assuming visual order is reading order. Absolutely positioned sidebars and
flex
ordervalues are read where they sit in the DOM. - Testing only the happy path. Errors, empty states and dialogs (steps 8 to 10) are where these criteria are actually decided.
- Overcorrection — adding positive
tabindexto "fix" focus order.tabindex="1"throws an element to the front of the sequence and breaks the natural order everywhere else. Fix the DOM order instead.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

