Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

waitFor passes too early, never retries or times out in a React test

ErrorUnable to find an element

Short 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.

  • Applies to @testing-library/react 16, @testing-library/dom 10, Jest 29
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 await
  2. 2Match what you see, then jump to its fix

    1. 1The test ends green, the assertion after it fails randomly or the test logs after finishingwaitFor is not awaitedFix
    2. 2waitFor resolves immediately although the UI has not changedThe callback returns a value instead of throwingFix
    3. 3Timed out in waitFor after 1000 msThe work takes longer than the default timeoutFix
    4. 4The element is visible in the printed DOM but never foundThe element is outside the container being watchedFix

What does the error look like?

  • Unable to find an element
  • Timed 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 await

2Fix

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.jsx

Confirmed by testing-library.com

Did this fix it?

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.jsx

Confirmed by testing-library.com

Did this fix it?

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.js

2Fix

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.jsx

Confirmed by testing-library.com

Did this fix it?

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.jsx

Confirmed by testing-library.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.