# Feature catalog — testing-library/dom-testing-library

> Canonical page: https://codevetter.com/unpack/dom-testing-library/feature-catalog

# Feature catalog — testing-library/dom-testing-library

Scanned commit 6049cc0bc7cf2201625c476c95fa6299d0e2fa8b (2026-09-13). Generated by codevetter codevetter 1.15.0 on 2026-10-02.

Source inspection; upstream code and tests were not executed.

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. — [src/query-helpers.ts#L63-L84](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/query-helpers.ts#L63-L84) [src/query-helpers.ts#L101-L139](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/query-helpers.ts#L101-L139) [src/query-helpers.ts#L224-L256](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/query-helpers.ts#L224-L256)
- 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. — [src/queries/role.ts#L42-L75](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/role.ts#L42-L75) [src/queries/role.ts#L120-L174](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/role.ts#L120-L174) [src/queries/role.ts#L192-L304](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/role.ts#L192-L304) [types/queries.d.ts#L69-L137](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/types/queries.d.ts#L69-L137)
- 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. — [src/queries/label-text.ts#L49-L84](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/label-text.ts#L49-L84) [src/queries/label-text.ts#L110-L164](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/label-text.ts#L110-L164) [src/label-helpers.ts#L57-L81](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/label-helpers.ts#L57-L81)
- 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. — [src/queries/text.ts#L18-L45](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/text.ts#L18-L45) [src/get-node-text.ts#L3-L13](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/get-node-text.ts#L3-L13) [src/matches.ts#L19-L76](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/matches.ts#L19-L76)
- 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. — [src/queries/display-value.ts#L17-L43](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/display-value.ts#L17-L43) [src/queries/placeholder-text.ts#L6-L9](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/placeholder-text.ts#L6-L9) [src/queries/alt-text.ts#L13-L24](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/alt-text.ts#L13-L24) [src/queries/title.ts#L17-L36](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/title.ts#L17-L36) [src/queries/test-id.ts#L6-L16](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/queries/test-id.ts#L6-L16)
- within/getQueriesForElement binds a supplied query map to a container; screen provides body-bound default queries plus debug and logTestingPlaygroundURL helpers. — [src/index.js#L19-L26](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/index.js#L19-L26) [src/get-queries-for-element.js#L13-L22](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/get-queries-for-element.js#L13-L22) [src/screen.ts#L24-L54](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/screen.ts#L24-L54)
- 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. — [src/event-map.js#L1-L83](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/event-map.js#L1-L83) [src/event-map.js#L385-L387](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/event-map.js#L385-L387) [src/events.js#L32-L48](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/events.js#L32-L48) [src/events.js#L65-L101](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/events.js#L65-L101) [src/events.js#L125-L130](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/events.js#L125-L130)
- 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. — [src/wait-for.js#L136-L179](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/wait-for.js#L136-L179) [src/wait-for-element-to-be-removed.js#L15-L46](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/wait-for-element-to-be-removed.js#L15-L46) [src/suggestions.js#L76-L135](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/suggestions.js#L76-L135) [src/pretty-dom.js#L48-L105](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/pretty-dom.js#L48-L105) [src/role-helpers.js#L160-L231](https://github.com/testing-library/dom-testing-library/blob/6049cc0bc7cf2201625c476c95fa6299d0e2fa8b/src/role-helpers.js#L160-L231)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)