$ show testing-library/jest-dom
This repository is the `@testing-library/jest-dom` library, a widely-used collection of custom Jest matchers for asserting the state of DOM elements in tests. It provides over 30 matchers such as `toBeVisible`, `toBeDisabled`, `toHaveAttribute`, `toHaveFormValues`, and `toHaveAccessibleName`, enabling declarative and readable test assertions. The library is designed to work with Jest, Vitest, Bun, and any Jest-compatible `expect` interface, with dedicated entry points for each. It leverages dependencies like `aria-query` and `dom-accessibility-api` to support accessibility-related matchers, and `@adobe/css-tools` for CSS style assertions. The codebase is well-structured, with each matcher in its own file, a shared utility module, and a factory pattern for generating query-based matchers (`toContainAnyBy*` / `toContainOneBy*`). Comprehensive tests and TypeScript type definitions are included. The library is actively maintained with frequent releases and a large contributor base.
The LLM identified 5 files worth highlighting for reuse:
Implements a factory function `createQueryMatcher` that dynamically generates matchers (`toContainAnyBy*` and `toContainOneBy*`) for any Testing Library query (e.g., byRole, byText, byTestId). It converts query names to PascalCase, looks up the corresponding `queryAllBy*` function, and returns a matcher that checks the count of matching descendants. This pattern reduces boilerplate and demonstrates a clean, reusable approach to creating matchers from existing query functions. The module is self-contained aside from importing `checkHtmlElement` and `getMessage` from `./utils`, and could be extracted to generate custom matchers for any DOM query API.
Provides the `toHaveFormValues` matcher, which asserts that a form or fieldset contains form controls with specified values. It handles a wide variety of input types: text, number, checkbox (single and multiple), radio groups, select (single and multiple), and textarea. The logic abstracts away the differences in how each control exposes its value (e.g., `value` attribute, `checked` property, `selected` options). It also supports array comparison for multi-select and checkbox groups, and correctly handles empty values and null. The implementation is robust and well-tested, making it a strong candidate for reuse in any project needing form value assertions.
Implements the `toBeVisible` matcher by checking multiple conditions: presence in the document, computed CSS properties (`display`, `visibility`, `opacity`), the `hidden` attribute, and the `open` attribute on `<details>` elements. It recursively checks parent visibility, correctly handling nested `<details>` and `<summary>` elements. The logic is self-contained and demonstrates a thorough understanding of DOM visibility semantics. This module could be extracted as a standalone visibility checker for DOM nodes.
Provides the `toHaveSelection` matcher, which checks if a given text selection (via `Document.getSelection()`) matches an expected string. It handles form elements (`input`, `textarea`) using `selectionStart`/`selectionEnd`, and other elements by manipulating DOM ranges. The logic correctly handles cases where the selection is wholly inside the element, partially overlaps, or the element contains the selection. It temporarily modifies the selection to compute the string and restores it afterward. This is a non-trivial use of the DOM Selection API and demonstrates careful state management.
A collection of shared utility functions used across all matchers. Key functions include `checkHtmlElement` and `checkNode` for validating that arguments are DOM elements/nodes with proper error messages, `parseCSS` for safely parsing CSS strings using `@adobe/css-tools`, `getSingleElementValue` for extracting values from various form controls (input, select, textarea, ARIA roles), `normalize` for whitespace normalization, `compareAsSet` for array comparison, and `getMessage` for formatting assertion failure messages. These utilities are well-factored, handle edge cases (e.g., `Document` objects that throw on `printWithType`), and could be extracted into a separate package for DOM testing helpers.