queryByText

queryByText is a non-throwing query function in React Testing Library used to locate elements by their visible text. It searches the DOM within a given container (or the global document via the screen object) and returns the first element whose text content matches the provided value. If no element matches, it returns null. If multiple elements match, it returns the first match.

This function is typically used when tests need to verify the presence or absence of text without causing exceptions if the element is missing. It is especially helpful for assertions about what is shown to the user or to confirm that certain text has been removed from the UI.

Compared with getByText, which throws when there is no match (and often when there are multiple matches), queryByText provides a non-throwing alternative for single-element queries. It differs from queryAllByText, which returns an array of all matching elements; queryByText returns only a single element (the first match) or null.

Usage generally involves providing a text value or a regular expression to match against the element’s visible text, with optional constraints to limit the search to a specific container or to customize the matching behavior. It is commonly used in conjunction with render or screen to support assertions about text visibility in the UI. See also: getByText, queryAllByText, screen.