Registry / testing / extend-to-be-announced

extend-to-be-announced

library2.0.0jsnpmunverified

`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.

testing

npm install extend-to-be-announced

github ↗package ↗

INSTALL

IMPORT

SIG · EXTEND-TO-BE-ANNOU

extend-to-be-announced

testingjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Vitest Setup

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

✗ const setup = require('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

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

✗ const setup = require('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

✓ import { register } from 'extend-to-be-announced/vitest/register';

✗ 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.

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(); }); });

Debug

Known issues

breakingVersion 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)@)']`.

affects: >=2.0.0

gotchaARIA 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.

affects: >=1.0.0

gotchaWhen 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 });`

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

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

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';`.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

aria-live-capturerequiredInternal dependency for detecting ARIA live region announcements, underwent a breaking change to ESM-only in v2.0.0 of this package.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/AriPerkkio/extend-to-be-announced ↗

packagehttps://www.npmjs.com/package/extend-to-be-announced ↗