aria-live-capture

Installation | Usage | Announcement detection examples | Support

Capture announcements of ARIA live regions.

aria-live-capture is an utility tool for inspecting announcements of ARIA live regions. When developing an application which utilizes ARIA live announcements it is often frustrating to toggle screen readers and other assistive technologies constantly on/off during development. This tool aims to help developers easily see announcements without having to use actual screen readers. However final assertion should always be made with the actual target assistive technology.

For online demo see Storybook playground.

For validating ARIA live regions in tests see extend-to-be-announced.

For Storybook integration see storybook-addon-aria-live.

Read more about inspiration from Building testing tools for ARIA live regions.

Installation

aria-live-capture should be included in development dependencies.

npm install --save-dev aria-live-capture

Usage

Import CaptureAnnouncements from entrypoint.

import CaptureAnnouncements from 'aria-live-capture';

onCapture

Pass onCapture callback to handle announcements.

Callback argument	type	value
announcement	string	Text content of the announcement
politenessSetting	string	polite|assertive

CaptureAnnouncements({
    onCapture: (announcement, politenessSetting) => {
        console.log(`"${announcement}" was announced with politeness setting "${politenessSetting}"`);
    },
});

"Loading" was announced with politeness setting "polite"
"Failed to load user details" was announced with politeness setting "assertive"

includeShadowDom

Pass an optional boolean includeShadowDom option to include tracking of live regions in Shadow DOM. Default value is false.

CaptureAnnouncements({
    includeShadowDom: true,
});

cleanup

The CaptureAnnouncements method returns cleanup function for clearing DOM interceptors.

const cleanup = CaptureAnnouncements(options);

cleanup();

Announcement detection examples

Test online  

Render#1 | <div role="status"></div>
Render#2 | <div role="status">Loading</div>
PASS ✅  | "Loading" is announced

Render#1 | <div aria-live="polite"></div>
Render#2 | <div aria-live="polite">Loading</div>
PASS ✅  | "Loading" is announced

Render#1 | <div role="log"></div>
Render#2 | <div role="log">Loading</div>
PASS ✅  | "Loading" is announced

Render#1 | <output></output>
Render#2 | <output>Loading</output>
PASS ✅  | "Loading" is announced

Render#1 | <div role="status">Loading</div>
FAIL ❌  | "Loading" is not announced

Render#1 | <div></div>
Render#2 | <div role="status">Loading</div>
FAIL ❌  | "Loading" is not announced

Render#1 | <div></div>
Render#2 | <div aria-live="polite">Loading</div>
FAIL ❌  | "Loading" is not announced

Render#1 | <div role="alert">Error</div>
PASS ✅  | "Error" is announced

Render#1 | <div aria-live="assertive">Error</div>
FAIL ❌  | "Error" is not announced

Render#1 | <div></div>
Render#2 | <div role="alert">Error</div>
PASS ✅  | "Error" is announced

Render#1 | <div role="status">
         |     <div aria-hidden="true">Loading</div>
         | </div>
         |
Render#2 | <div role="status">
         |     <div aria-hidden="false">Loading</div>
         | </div>
         |
PASS ✅  | "Loading" is announced

Render#1 | <div role="status" aria-hidden="true">Loading</div>
Render#2 | <div role="status" aria-hidden="false">Loading</div>
FAIL ❌  | "Loading" is not announced

With option { includeShadowDom: true }:

Render#1 | <div role="status">
         |     #shadow-root
         |     <div></div>
         | </div>
         |
Render#2 | <div role="status">
         |     #shadow-root
         |     <div>Loading</div>
         | </div>
         |
PASS ✅  | "Loading" is announced

Support

Feature	Status
role	✅
aria-live	✅
aria-atomic	❌ 👷
aria-busy	❌
aria-relevant	❌