screen-reader-testing

Files (5)

• SKILL.md
• jaws-talkback.md · references/
• nvda.md · references/
• voiceover-ios.md · references/
• voiceover.md · references/

SKILL.md (first lines)

# Screen Reader Testing

Practical guide to testing web applications with screen readers for comprehensive accessibility validation.

## When to Use This Skill

- Validating screen reader compatibility
- Testing ARIA implementations
- Debugging assistive technology issues
- Verifying form accessibility
- Testing dynamic content announcements
- Ensuring navigation accessibility

## Core Concepts

### 1. Major Screen Readers

| Screen Reader | Platform  | Browser        | Usage |
| ------------- | --------- | -------------- | ----- |
| **VoiceOver** | macOS/iOS | Safari         | ~15%  |
| **NVDA**      | Windows   | Firefox/Chrome | ~31%  |
| **JAWS**      | Windows   | Chrome/IE      | ~40%  |
| **TalkBack**  | Android   | Chrome         | ~10%  |
| **Narrator**  | Windows   | Edge           | ~4%   |

### 2. Testing Priority

```
Minimum Coverage:
1. NVDA + Firefox (Windows)
2. VoiceOver + Safari (macOS)
3. VoiceOver + Safari (iOS)

Comprehensive Coverage:
+ JAWS + Chrome (Windows)
+ TalkBack + Chrome (Android)
+ Narrator + Edge (Windows)
```

### 3. Screen Reader Modes

| Mode               | Purpose                | When Used         |
| ------------------ | ---------------------- | ----------------- |
| **Browse/Virtual** | Read content           | Default reading   |
| **Focus/Forms**    | Interact with controls | Filling forms     |
| **Application**    | Custom widgets         | ARIA applications |

Before testing on macOS, read [VoiceOver setup, commands, and checklists](references/voiceover.md).

For the required iOS Safari coverage, read [VoiceOver touch setup and gestures](references/voiceover-ios.md).

Before testing with NVDA, read [NVDA setup, modes, commands, and test scripts](references/nvda.md).

Before testing with JAWS or TalkBack, read [platform setup and commands](references/jaws-talkback.md).

## Common Test Scenarios

### 1. Modal Dialog

Prefer native `<dialog>` opened with `showModal()`: the browser makes the rest of the page inert, traps focus, closes on Escape, and exposes `role="dialog"` with `aria-modal` semantics.

```html
<dialog id="confirm-delete" aria-labelledby="dialog-title" aria-describedby="dialog-desc">
  <h2 id="dialog-title" tabindex="-1">Confirm Delete</h2>
  <p id="dialog-desc">This action cannot be undone.</p>
  <button type="button" data-close>Cancel</button>
  <button type="button">Delete</button>
</dialog>
```

```javascript
// Focus management: the heading needs tabindex="-1" to receive programmatic focus
const dialog = document.getElementById("confirm-delete");
let lastFocus = null;

function openDialog() {
  lastFocus = document.activeElement;
  dialog.showModal(); // inert background + focus containment + Escape to close
  dialog.querySelector("#dialog-title").focus();
}

dialog.addEventListener("close", () => {
  lastFocus?.focus(); // fires for Escape and dialog.close() alike
});

dialog.querySelector("[data-close]").addEventListener("click", () => dialog.close());
```

Test: on open, the screen reader announces the dialog name, role and description; Tab never reaches page content behind it; on close, focus lands back on the trigger.

### 2. Live Regions

```html
<!-- Status messages (polite) -->
<div role="status" aria-live="polite" aria-atomic="true">
  <!-- Content updates will be announced after current speech -->
</div>

<!-- Alerts (assertive) -->
<div role="alert" aria-live="assertive">
  <!-- Content updates interrupt current speech -->
</div>

<!-- Progress updates -->
<div
  role="progressbar"
  aria-valuenow="75"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-label="Upload progress"
></div>

<!-- Log (additions only) -->
<div role="log" aria-live="polite" aria-relevant="additions">
  <!-- New messages announced, removals not -->
</div>
```

### 3. Tab Interface

From shotcowboystyle/ag-skills, MIT.

More from shotcowboystyle/ag-skills