queryAllBy

queryAllBy is a function in the React Testing Library query API used to locate elements in the rendered output. It returns an array containing all elements that match the given query within a specified container. If no elements match, it returns an empty array instead of throwing an error. This non-throwing behavior distinguishes it from the getAllBy family.

As a counterpart to getAllBy, queryAllBy provides a safe way to discover multiple matches without risking an exception when none exist. It is useful when you expect more than one element to satisfy the query or when you want to assert the number of matches by inspecting the resulting array length. The function supports the same query modalities as other RTL queries, such as text, role, label text, test id, and more. Typical usages include queryAllByText, queryAllByRole, queryAllByLabelText, and queryAllByTestId, often in conjunction with within to constrain the search to a subelement.

The return value is always an array of elements, which makes it straightforward to perform assertions on the number of matches or to iterate over findings. queryAllBy is synchronous and does not involve waiting for elements to appear, unlike some findBy variants.

When to use it: choose queryAllBy when you want to retrieve every element that matches a query and you want to handle the possibility of zero results gracefully. If you require a single element and want strict failure when there are zero or multiple matches, use getBy* or queryBy* as appropriate.

---