Course contentsShow
← React
Lesson 2060 of 2,39646. Testing React with RTLFree lesson

getAllBy, queryAllBy, findAllBy for Multiple Elements

The plural query variants that return arrays instead of single elements.

getAllBy, queryAllBy, findAllBy for Multiple Elements

What you'll learn: How to query for multiple matching elements instead of just the first one using RTL's plural query variants.

The Core Idea

Every query method you've learned (getByRole, queryByText, findByLabelText, etc.) has a plural counterpart that returns an array of all matching elements instead of just the first match. The pattern is simple: getBy becomes getAllBy, queryBy becomes queryAllBy, and findBy becomes findAllBy.

When You Need Plural Queries

Imagine testing a todo list with multiple checkboxes, a navigation menu with several links, or a table with multiple rows. The singular queries would only find the first element, but you often need to assert on all of them — their count, their order, or their collective state.

The Three Variants

getAllBy: Multiple Elements, Must Exist

Returns an array. Throws an error if zero elements match. Use when elements must be present synchronously.

queryAllBy: Multiple Elements, May Not Exist

Returns an array (empty if nothing matches). Never throws. Use to assert that multiple elements are absent.

findAllBy: Multiple Elements, Appear Asynchronously

Returns a Promise resolving to an array. Waits for elements to appear. Use for async-loaded lists.

The Mental Model

Think of singular queries as "find me the button" and plural queries as "find me all the buttons." The error behavior mirrors the singular versions: getAll and findAll demand matches, while queryAll tolerates absence.

Key Takeaway: Use getAllBy, queryAllBy, and findAllBy when you need to work with multiple matching elements — they return arrays and follow the same sync/async/nullable patterns as their singular counterparts.