queryByRole

queryByRole is a query function from DOM Testing Library (used by React Testing Library) that locates a single element by its ARIA role. It searches the rendered DOM for elements with the specified role and optional accessible name, and returns the first match. If no element matches, it returns null. It does not throw on a missing element, making it useful for tests that need to assert absence or optional presence.

Usage and options: queryByRole can be called with a container or via screen, e.g., screen.queryByRole('button') or screen.queryByRole('heading', { level: 2 }). The role value corresponds to ARIA roles such as button, textbox, link, heading, img, and more. The options object can refine the search by accessible name using name: string or a regular expression, and can include hidden: true to consider elements that are visually hidden. For headings, level can be specified to target a specific heading level (e.g., level: 2).

Relation to other queries: queryByRole is part of a family that includes getByRole, queryAllByRole, and findByRole. getByRole throws if no match or multiple matches; queryAllByRole returns all matches; findByRole is asynchronous. Use queryByRole when the element may not be present and you want to handle that case gracefully.

Accessibility emphasis: queryByRole leverages the accessibility tree to promote tests that reflect how users interact with the UI, rather than relying on implementation details like test IDs. It is commonly used for locating interactive elements and validating their presence or absence in a component.