National Poo Museum

    extend-to-be-announced
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    extend-to-be-announced

    version

    Motivation | Installation | Usage | Support

    Utility for asserting ARIA live regions.

    extend-to-be-announced is a matcher extender for Jest and Vitest. It makes validating ARIA live regions extremely easy. Internally it is utilizing aria-live-capture for announcement detection.

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

    Motivation

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

    Validating ARIA live regions with @testing-library and jest-dom requires developers to consider implementation details. Current solutions are prone to false positives.

    In test below it is not clearly visible that Loading... is not actually announced. Assistive technologies are only expected to announce updates of ARIA live regions - not the initial content.

    render(<div role="status">Loading...</div>);
    
    const liveRegion = screen.getByRole('status');
    
    // Loading is not be announced by assistive technologies ❌
    // Content of live region has not updated. This is it's initial text content.
    expect(liveRegion).toHaveTextContent('Loading...');

    Instead developers should check that messages are rendered into existing ARIA Live regions.

    const { rerender } = render(<div role="status"></div>);
    
    // Live region should be present
    const liveRegion = screen.getByRole('status');
    
    // Live region should initially be empty
    expect(liveRegion).toBeEmptyDOMElement();
    
    // Update content of the live region
    rerender(<div role="status">Loading...</div>);
    
    // Loading is announced by assistive technologies ✅
    expect(liveRegion).toHaveTextContent('Loading...');

    toBeAnnounced can be used to hide such implementation detail from tests.

    const { rerender } = render(<div role="status"></div>);
    
    rerender(<div role="status">Loading...</div>);
    
    expect('Loading...').toBeAnnounced('polite');

    Installation

    extend-to-be-announced should be included in development dependencies.

    yarn add --dev extend-to-be-announced

    Usage

    Test setup

    There are out-of-the-box setups for Jest and Vitest.

    Jest

    Import registration entrypoint in your test setup.

    import 'extend-to-be-announced/jest';

    For setting up registration options use register(options) method instead.

    import { register } from 'extend-to-be-announced/jest/register';
    
    register({
        /** Indicates whether live regions inside `ShadowRoot`s should be tracked. Defaults to false. */
        includeShadowDom: true,
    });

    Vitest

    Import registration entrypoint in your test setup.

    import 'extend-to-be-announced/vitest';

    Vitest also requires all dependencies that import Vitest internally to be inlined. Add extend-to-be-announced to your configuration's test.deps.inline array:

    // vitest.config.ts
    import { defineConfig } from 'vitest/config';
    
    export default defineConfig({
        test: {
            deps: {
                inline: ['extend-to-be-announced'],
            },
        },
    });

    For setting up registration options use register(options) method instead.

    import { register } from 'extend-to-be-announced/vitest/register';
    
    register({
        /** Indicates whether live regions inside `ShadowRoot`s should be tracked. Defaults to false. */
        includeShadowDom: true,
    });

    Typescript

    This package utilizes Typescript's exports support for type declarations. You'll need to set "moduleResolution": "node16" or "moduleResolution": "nodenext" in your tsconfig.json in order to have typings picked properly. For legacy setups where certain fields of tsconfig.json cannot be modified, such as create-react-app, there is a work-around entrypoint for jest.

    {
        "compilerOptions": {
            "moduleResolution": "node16" // Or nodenext
        }
    }

    Assertions

    toBeAnnounced

    Assert whether given message was announced by assistive technologies. Accepts string or regexp as matcher value.

    expect('Loading...').toBeAnnounced();
    expect(/loading/i).toBeAnnounced();
    expect('Error occured...').toBeAnnounced();
    expect(/error occured/i).toBeAnnounced();

    Politeness setting of announcement can be optionally asserted.

    expect('Loading...').toBeAnnounced('polite');
    expect('Error occured...').toBeAnnounced('assertive');
    Examples
    Render#1 | <div role="status"></div>
    Render#2 | <div role="status">Loading</div>
    PASS ✅  | expect('Loading').toBeAnnounced('polite');
    Render#1 | <div role="alert">Error</div>
    PASS ✅  | expect('Error').toBeAnnounced('assertive');
    Render#1 | <div></div>
    Render#2 | <div role="alert">Error</div>
    PASS ✅  | expect('Error').toBeAnnounced();
    Render#1 | <div role="status">Loading</div>
    FAIL ❌  | expect('Loading').toBeAnnounced();
    Render#1 | <div></div>
    Render#2 | <div role="status">Loading</div>
    FAIL ❌  | expect('Loading').toBeAnnounced();

    With register({ includeShadowDom: true }):

    Render#1 | <div role="status">
             |     #shadow-root
             |     <div></div>
             | </div>
             |
    Render#2 | <div role="status">
             |     #shadow-root
             |     <div>Loading</div>
             | </div>
             |
    PASS ✅  | expect('Loading').toBeAnnounced()

    Utilities

    getAnnouncements

    Get all announcements as Map<string, PolitenessSetting>.

    import { getAnnouncements } from 'extend-to-be-announced';
    getAnnouncements();
    
    > Map {
    >   "Status message" => "polite",
    >   "Alert message" => "assertive",
    > }

    clearAnnouncements

    Clear all captured announcements.

    import { clearAnnouncements } from 'extend-to-be-announced';
    clearAnnouncements();

    Support

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

    Keywords

    none

    Install

    npm i extend-to-be-announced

    DownloadsWeekly Downloads

    2

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    32.2 kB

    Total Files

    22

    Last publish

    Collaborators

    • ariperkkio