Async Queries, waitFor & act

## The problem: the DOM at t=0 is not the DOM you are asserting about A component that fetches on mount renders twice, at minimum: once immediately (empty, skeleton, or loading state) and again after the promise resolves and React re-renders. `render()` returns after the first of those. Any assertion written on the next line runs against the *first* DOM, which does not yet contain the fetched name. The test does not need a longer sleep — it needs a query that keeps looking. ## What findBy* actually is Every async query in Testing Library is defined as the synchronous query wrapped in the `waitFor` helper. `findByText(...)` is roughly `waitFor(() => getByText(...))`. That gives it three properties worth stating explicitly: - **It returns a promise.** Nothing in it is synchronous. - **It retries.** The underlying `waitFor` observes the container with a `MutationObserver` and also polls on an interval (50 ms by default), re-running the query each time something could have changed. - **It has a deadline.** The default is 1000 ms, exposed as the `asyncUtilTimeout` configuration value. On timeout it rejects with the same readable error a `getBy*` failure produces, including a printout of the DOM it searched, which is usually enough to see that you were waiting on the wrong text. ```js expect(await screen.findByText('Ada Lovelace')).toBeInTheDocument() ``` Because the query itself throws a descriptive error on failure, the `expect` around it is close to redundant — many teams write `await screen.findByText('Ada Lovelace')` on its own line and treat the absence of a rejection as the assertion. ## Why the await is not optional Dropping the `await` breaks the test in two directions at once. Forward: `expect(somePromise).toBeInTheDocument()` is asserting on a promise object, and depending on your matcher set it either fails with a confusing message or, worse, silently passes a truthiness-shaped check. Backward: the retry loop is still running after the test function returns. When the fetch resolves and React sets state, it does so in a component belonging to a test that has already finished — React emits the "An update to X inside a test was not wrapped in act(...)" warning, the failure surfaces in a *different* test's output, and the suite becomes hard to read. Linting helps here; the `await-async-queries` rule in eslint-plugin-testing-library exists precisely because this mistake is invisible when the test happens to pass. ## Passing options The async queries take the query options as the second argument and the wait options as the third, so a slower path is expressed as: ```js await screen.findByText('Ada Lovelace', {}, { timeout: 3000 }) ``` The empty object in the middle is the query options slot. You can also move the default globally with `configure({ asyncUtilTimeout: 3000 })`, but a global bump slows every failing test in the suite by the same factor, so a local option with a comment is usually the better trade. ## findAllBy* and the "at least one" rule `findAllBy*` resolves with an **array** and is satisfied as soon as one element matches. If the component streams in rows, it can resolve when three of the expected ten have rendered. When the count matters, wait for something that only exists in the final state — a total label, an enabled button — rather than asserting the array length straight out of `findAllBy*`. ## What findBy* does not do It does not wait for the network, a timer, or a promise; it only watches the DOM. If the component never renders the text — wrong prop, mock not wired, error branch taken — you get a one-second delay and then a failure, which is the correct outcome. And it is not a substitute for making the test deterministic: an arbitrary `setTimeout` sleep before a synchronous `getBy*` is the anti-pattern that `findBy*` replaces, because a sleep is simultaneously too long on a fast machine and too short on a loaded CI runner.