waitFor passes too early, never retries or times out in a React test
Unable to find an elementShort answer
waitFor retries its callback only when the callback throws. A callback that returns false, or that has no assertion, passes on the first run. The call must also be awaited, and the default timeout is 1000 ms. Put a real expect inside, await it, and raise the timeout for slow work.
Fix it fast
1Find out which cause you have
Check that the line starts with await, and that the callback contains an expect (or a getBy query) that throws when the UI is not ready.
grep -rn "waitFor(" src/ | grep -v await2Match what you see, then jump to its fix
- 1
The test ends green, the assertion after it fails randomly or the test logs after finishingwaitFor is not awaitedFix - 2
waitFor resolves immediately although the UI has not changedThe callback returns a value instead of throwingFix - 3
Timed out in waitFor after 1000 msThe work takes longer than the default timeoutFix - 4
The element is visible in the printed DOM but never foundThe element is outside the container being watchedFix
- 1
What does the error look like?
Unable to find an elementTimed out in waitFor.test passes before the UI has updated
Cause 1 of 4
waitFor is not awaited
1Check
waitFor is async and returns a promise. Without await the test function moves on at once.
grep -rn "waitFor(" src/ | grep -v await2Fix
Await it, and mark the test function async.
test('shows the result', async () => {
render(<Search />);
await waitFor(() => expect(screen.getByText('Done')).toBeInTheDocument());
});3Verify
Break the expected text on purpose. The test must now fail after about one second.
npx jest src/Search.test.jsxConfirmed by testing-library.com
Cause 2 of 4
The callback returns a value instead of throwing
1Check
Only a thrown error triggers a retry. Returning false or null is not enough, so a callback like () => ready === true passes on its first run.
grep -rn "waitFor(() =>" src/2Fix
Use an assertion that throws on failure.
await waitFor(() => {
expect(screen.getByRole('status')).toHaveTextContent('Saved');
});3Verify
With the UI still loading, the call keeps retrying and then times out.
npx jest src/Search.test.jsxConfirmed by testing-library.com
Cause 3 of 4
The work takes longer than the default timeout
1Check
The default timeout is 1000 ms and the callback runs every 50 ms. A slow mocked request or animation can need longer.
grep -rn "timeout" src/ jest.config.js2Fix
Raise the timeout for that call, or switch to findBy, which takes the same options.
await waitFor(() => expect(screen.getByText('Done')).toBeVisible(), { timeout: 3000 });
await screen.findByText('Done', {}, { timeout: 3000 });3Verify
The test passes once the element appears.
npx jest src/Search.test.jsxConfirmed by testing-library.com
Cause 4 of 4
The element is outside the container being watched
1Check
The container defaults to the global document, and awaited elements must be descendants of it. A custom container option can exclude them.
grep -rn "container" src/2Fix
Remove the custom container or point it at an ancestor of the element.
await waitFor(() => expect(screen.getByText('Done')).toBeInTheDocument(), {
container: document.body,
});3Verify
The element is found within the timeout.
npx jest src/Search.test.jsxConfirmed by testing-library.com
How do I stop it coming back?
- Prefer findBy queries when you are only waiting for one element to appear.
- Keep one assertion idea per waitFor and no side effects inside, because the callback can run many times.
- Lint with eslint-plugin-testing-library to catch un-awaited async utilities.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
A React test warns that a state update was not wrapped in act()
Warning: The current testing environment is not configured to support act(...)
The warning means React state changed while your test was not waiting for it.
4 causes, each with a fixWeb apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fix