{"id":16356,"library":"extend-to-be-announced","title":"Jest/Vitest Matcher for ARIA Live Regions","description":"`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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/AriPerkkio/extend-to-be-announced","tags":["javascript","typescript"],"install":[{"cmd":"npm install extend-to-be-announced","lang":"bash","label":"npm"},{"cmd":"yarn add extend-to-be-announced","lang":"bash","label":"yarn"},{"cmd":"pnpm add extend-to-be-announced","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency for detecting ARIA live region announcements, underwent a breaking change to ESM-only in v2.0.0 of this package.","package":"aria-live-capture","optional":false}],"imports":[{"note":"This import registers the `toBeAnnounced` matcher globally for Vitest. Ensure this is included in your Vitest setup files.","wrong":"const setup = require('extend-to-be-announced/vitest');","symbol":"Vitest Setup","correct":"import 'extend-to-be-announced/vitest';"},{"note":"This import registers the `toBeAnnounced` matcher globally for Jest. Ensure this is included in your Jest `setupFilesAfterEnv` configuration.","wrong":"const setup = require('extend-to-be-announced/jest');","symbol":"Jest Setup","correct":"import 'extend-to-be-announced/jest';"},{"note":"Use named import for the `register` function to configure options like `includeShadowDom`. Requires separate import from the default setup entrypoint.","wrong":"import register from 'extend-to-be-announced/vitest/register';","symbol":"Vitest Register Options","correct":"import { register } from 'extend-to-be-announced/vitest/register';"}],"quickstart":{"code":"import { render, screen, cleanup } from '@testing-library/react';\nimport { register } from 'extend-to-be-announced/jest/register';\n\n// Configure Jest setup if not done globally via setupFilesAfterEnv\nregister();\n\ndescribe('ARIA live region announcements', () => {\n afterEach(cleanup);\n\n it('announces content updates to polite live regions', () => {\n const { rerender } = render();\n // Initially empty, nothing to announce\n expect('').not.toBeAnnounced();\n\n // Update the content of the live region\n rerender(Loading data...
);\n\n // Expect 'Loading data...' to be announced politely\n expect('Loading data...').toBeAnnounced('polite');\n });\n\n it('does not announce initial content of a live region', () => {\n render(Initial Message
);\n // The initial content 'Initial Message' should not be announced\n expect('Initial Message').not.toBeAnnounced();\n });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"For Jest, add `aria-live-capture` to your `transformIgnorePatterns` in `jest.config.js`. Example for pnpm: `transformIgnorePatterns: ['/node_modules/.pnpm/(?!(aria-live-capture)@)']`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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 });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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).","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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';`.","cause":"The Jest or Vitest matcher has not been registered correctly in your testing environment setup.","error":"TypeError: expect(...).toBeAnnounced is not a function"}],"ecosystem":"npm"}