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.