CodeVetter · Repo Unpack · Feature catalog
testing-library/dom-testing-library
Users locate elements by accessible semantics, visible text, form values, and identifying attributes. Each query family exposes variants for nullable lookup, required lookup, collections, and asynchronous lookup. Additional APIs scope queries, dispatch events, wait for disappearance, recommend queries, and print diagnostics. These are library APIs used from test code rather than application routes or screens.
- Query variants distinguish cardinality: queryBy returns null for no matches and throws for multiple matches; getAllBy throws for an empty result; getBy requires exactly one; find variants return waitFor-backed promises.
- ByRole supports explicit and implicit roles, accessible names/descriptions, hidden inclusion, fallback role tokens, selected/busy/checked/pressed/current/expanded states, heading level, and ARIA values; unsupported role-option combinations throw.
- ByLabelText resolves native labels, aria-labelledby, and aria-label, deduplicates matches, applies a selector, and distinguishes missing associations from labels attached to non-labellable elements.
- ByText accepts selector and ignore options, includes a matching element container, and uses immediate text nodes or button-like input values; matchers support exact strings, fuzzy strings, regular expressions, functions, and configurable normalization.
- ByDisplayValue matches input/textarea values or selected option text; PlaceholderText matches placeholder; AltText restricts matches to img/input/area/custom tags; Title includes SVG title children; TestId reads the configured attribute.
- within/getQueriesForElement binds a supplied query map to a container; screen provides body-bound default queries plus debug and logTestingPlaygroundURL helpers.
- createEvent and fireEvent provide registry-generated shortcuts for clipboard, keyboard, focus, form, mouse, and other events, including doubleClick aliasing; target values/files and transfer data can be supplied.
- waitFor retries callbacks and handles returned promises; waitForElementToBeRemoved requires initial presence; getSuggestedQuery ranks semantic alternatives; prettyDOM/logDOM and getRoles/logRoles expose DOM and accessibility diagnostics.