Jest/Vitest Matcher for ARIA Live Regions

2.0.0 · active · verified Wed Apr 22

`extend-to-be-announced` is a utility package providing custom Jest and Vitest matchers, specifically `toBeAnnounced`, for robustly testing ARIA live regions. It aims to simplify accessibility testing by abstracting away the complexities of how assistive technologies handle live region updates, preventing common false positives associated with simply checking DOM text content. The package is currently at version 2.0.0 and receives updates as needed, particularly when underlying dependencies or testing frameworks evolve. It differentiates itself by leveraging `aria-live-capture` internally to precisely detect actual announcements, ensuring tests reflect true user experience rather than just DOM state. This approach helps developers write more reliable and accurate accessibility tests, especially for dynamic content updates.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Jest is attempting to process the ESM-only `aria-live-capture` dependency without proper transpilation, usually because it's in `node_modules` and ignored by default.

fix Modify your Jest configuration's `transformIgnorePatterns` to include `aria-live-capture`. For example: `transformIgnorePatterns: ['/node_modules/.pnpm/(?!(aria-live-capture)@)']` (adjust for your package manager).
```
TypeError: expect(...).toBeAnnounced is not a function
```
cause The Jest or Vitest matcher has not been registered correctly in your testing environment setup.

fix Ensure you have imported the setup file in your test setup configuration (e.g., `setupFilesAfterEnv` for Jest, `setupFiles` for Vitest): `import 'extend-to-be-announced/jest';` or `import 'extend-to-be-announced/vitest';`.

Warnings

breaking Version 2.0.0 introduces a breaking change where its internal `aria-live-capture` dependency became ESM-only. This requires Jest users to update their configuration to correctly transpile this dependency.
Fix: For Jest, add `aria-live-capture` to your `transformIgnorePatterns` in `jest.config.js`. Example for pnpm: `transformIgnorePatterns: ['/node_modules/.pnpm/(?!(aria-live-capture)@)']`.
gotcha ARIA live regions are designed to announce *updates* to their content, not their initial content. Directly asserting `toHaveTextContent` on an initial live region can lead to false positives in accessibility tests.
Fix: Utilize `extend-to-be-announced`'s `toBeAnnounced` matcher, which correctly distinguishes between initial content and subsequent announcements. Always ensure the live region content is updated *after* initial render to trigger an announcement.
gotcha When working with Web Components or encapsulated components using Shadow DOM, `extend-to-be-announced` by default does not track live regions within `ShadowRoot`s.
Fix: Pass the `includeShadowDom: true` option to the `register` function when setting up the matcher, e.g., `import { register } from 'extend-to-be-announced/jest/register'; register({ includeShadowDom: true });`

Install

npm install extend-to-be-announced npm
yarn add extend-to-be-announced yarn
pnpm add extend-to-be-announced pnpm

Imports

Vitest Setup
wrong:
```
const setup = require('extend-to-be-announced/vitest');
```
correct:
```
import 'extend-to-be-announced/vitest';
```
This import registers the `toBeAnnounced` matcher globally for Vitest. Ensure this is included in your Vitest setup files.
Jest Setup
wrong:
```
const setup = require('extend-to-be-announced/jest');
```
correct:
```
import 'extend-to-be-announced/jest';
```
This import registers the `toBeAnnounced` matcher globally for Jest. Ensure this is included in your Jest `setupFilesAfterEnv` configuration.
Vitest Register Options
wrong:
```
import register from 'extend-to-be-announced/vitest/register';
```
correct:
```
import { register } from 'extend-to-be-announced/vitest/register';
```
Use named import for the `register` function to configure options like `includeShadowDom`. Requires separate import from the default setup entrypoint.

Quickstart

Demonstrates the basic usage of `toBeAnnounced` matcher for both Jest and Vitest, showing how to test for announced updates and avoid false positives with initial content.

import { render, screen, cleanup } from '@testing-library/react';
import { register } from 'extend-to-be-announced/jest/register';

// Configure Jest setup if not done globally via setupFilesAfterEnv
register();

describe('ARIA live region announcements', () => {
  afterEach(cleanup);

  it('announces content updates to polite live regions', () => {
    const { rerender } = render(<div role="status"></div>);
    // Initially empty, nothing to announce
    expect('').not.toBeAnnounced();

    // Update the content of the live region
    rerender(<div role="status">Loading data...</div>);

    // Expect 'Loading data...' to be announced politely
    expect('Loading data...').toBeAnnounced('polite');
  });

  it('does not announce initial content of a live region', () => {
    render(<div role="status">Initial Message</div>);
    // The initial content 'Initial Message' should not be announced
    expect('Initial Message').not.toBeAnnounced();
  });
});

view raw JSON →