Screen Reader Testing Tool for Developers

What Is a Screen Reader Testing Tool?

Screen reader testing tools analyze your HTML markup and predict how assistive technologies will interpret and announce it. They sit between writing code and launching a full screen reader, catching issues during development rather than after deployment.

Traditional accessibility testing tools (like axe-core or Lighthouse) check for rule violations: missing alt text, incorrect ARIA attributes, color contrast ratios. A screen reader testing tool goes further by answering the question: "What will users actually hear?" This includes announcement order, role descriptions, state communication, and the differences between how each screen reader phrases things.

Speakable is this kind of tool. It does not emulate a screen reader (no speech synthesis, no virtual cursor). Instead, it applies heuristic models based on documented screen reader behavior to predict the speech output line by line.

How Speakable Predicts Screen Reader Output

Speakable works in three stages: parse, extract, render.

1. Parse HTML

HTML is parsed using jsdom with error recovery. Malformed markup is handled gracefully, producing warnings rather than failing. This means you can feed it partial components, full pages, or even markup piped from a running dev server.

2. Extract Accessibility Tree

The parsed DOM is walked to build a canonical accessibility tree following the ARIA specification. Each node in the tree has a computed role, accessible name, description, value, states (expanded, selected, checked, disabled, required, etc.), and focus information. The accessible name computation follows the W3C accname algorithm.

3. Render Predictions

The accessibility tree is passed through heuristic renderers. Each renderer models the announcement patterns of a specific screen reader:

• NVDA: Announces name first, then role, then state. Uses "not selected", "unavailable" for disabled.
• JAWS: Similar to NVDA but strips some punctuation and sometimes adds context from parent containers.
• VoiceOver: Uses "unselected" instead of "not selected", says "dimmed" instead of "unavailable".
• Narrator: Adds interaction hints ("to activate, press Enter"), says "disabled" for unavailable elements.

Supported Screen Readers

All four major screen readers are supported on every plan, including free. You can target a single reader or compare all four simultaneously with -s all.

Getting Started in 60 Seconds

No configuration file, no account, no browser extension. Install and run:

# Analyze a file with all four screen readers
npx @reticular/speakable button.html -f text -s all

# Output:
# === NVDA ===
# Submit form, button
#
# === JAWS ===
# Submit form, button
#
# === VoiceOver ===
# Submit form, button
#
# === Narrator ===
# Submit form, button

Pipe HTML from a running server:

curl -s http://localhost:3000 | npx @reticular/speakable - -f text -s voiceover

Focus on a specific component using CSS selectors:

npx @reticular/speakable page.html -f text -s all --selector '[role="navigation"]'

What Screen Reader Testing Tools Catch

The value of predictive screen reader testing goes beyond what rule-based linters detect. Here are the categories of issues Speakable surfaces:

Missing Accessible Names

When a button, link, or form control has no computed name, the screen reader announces only the role ("button", "link") with no indication of purpose. Speakable's audit mode flags these immediately:

npx @reticular/speakable form.html -f audit
# Reports: "button with no accessible name at root.children[2]"

Incorrect ARIA Roles

A div with role="button" but missing keyboard handling, or a listbox without option children. The audit identifies structural ARIA misuse.

Heading Hierarchy Gaps

Screen reader users navigate by headings. A page that jumps from H1 to H3 creates a confusing navigation experience. The audit reports heading structure with level details.

Cross-Reader Announcement Differences

The most unique capability of a screen reader testing tool is showing how the same HTML produces different speech across readers. A component might say "unselected" on VoiceOver but "not selected" on NVDA. These differences matter for documentation and user support.

Comparing Screen Reader Testing Approaches

Different testing approaches serve different purposes. Here is how they compare:

The strongest workflow combines all three: Speakable in CI to catch regressions early, axe-core for rule violations, and manual screen reader testing before major releases.

Limitations and When to Use Real Screen Readers

Speakable is a development-time tool, not a replacement for testing with real assistive technology. Important limitations:

• Static HTML analysis only (does not execute JavaScript in the core CLI; use the runtime engine for dynamic behavior)
• Output is heuristic, not byte-for-byte identical to any screen reader version
• Does not account for user settings (verbosity, punctuation level, speech rate)
• Does not test browse mode vs focus mode behavior
• Does not test timing-dependent interactions (hover delays, animation sequences)
• Does not validate visual presentation (color contrast, font size, viewport behavior)

Use Speakable to catch the 80% of issues that are detectable from markup alone. Reserve manual screen reader testing for interaction patterns, timing, and the final user experience verification before release.