@testing-library/react behaves differently when dealing with Suspense in React 18 and React 19

[0xc14m1z]

• @testing-library/react version: 16.1.0
• Testing Framework and version: jest 29.7.0
• DOM Environment: jsdom 29.7.0

Relevant code or config:

render(
  <Suspense fallback="fallback">
    <TestComponent />
  </Suspense>
);

expect(screen.getByText("fallback")).toBeInTheDocument();
expect(await screen.findByText("resolved")).toBeInTheDocument();

What you did:

We're upgrading our codebase from React 18.3.1 to React 19.0.0.

What happened:

Over 300 tests started to fail because of suspended components kept rendering their fallbacks and never their children.

Reproduction:

In this repo we created a minimal reproduction for the issue we're facing.

It contains a folder react-18 and a folder react-19 that contains the same dependencies, configuration and code, except for the React version.

In both code bases there's the same test. It passes on the React 18 project, but fails in 2 different ways in the React 19 one.

Run npm test in each folder to see the output.

Problem description:

By default, a test that uses Suspense gets stuck rendering the fallback on React 19.

RTL emits a warning to wrap the render method in an awaited act. Following the suggestion leads the component to un-suspend, but make it impossible to assert against its fallback.

Suggested solution:

We don't have a solution for this problem, but we think RTL should behave the same with React 18 and React 19.

[MatanBobi]

Thanks @0xc14m1z.
@eps1lon I think we should move forwards with the open PR we have for await act.. Wdyt?

[centraldogma99]

I am also experiencing a similar issue. Same test code worked in React 18, but broken after upgrading to React 19.

Prerequisites

• Using fake timers.
• The component under test fetches data and displays a suspense fallback during the fetch.

Steps to Reproduce

1. Create a test case that renders a specific component and uses a findBy query to locate specific text displayed after the data fetch completes.
2. Copy and paste the the case multiple times within the same file.
3. Run the test file.
4. Only the first test case executed passes, while the others fail. The failing test cases remain in a suspended state. Occasionally, test cases other than the first one also pass, but this is intermittent.

Workaround

(This seems to not apply to all cases, but I am noting it just for reference)
I replaced the findBy query with the following workaround:

Before

await screen.findByRole('heading', { level: 1 });

After

const temp = globalThis.IS_REACT_ACT_ENVIRONMENT;
globalThis.IS_REACT_ACT_ENVIRONMENT = false;
const result = await vi.waitFor(() => {
  screen.getByRole('heading', { level: 1 });
});
globalThis.IS_REACT_ACT_ENVIRONMENT = temp;

[eps1lon]

I think we should move forwards with the open PR we have for await act.. Wdyt?

That's the plan for January. Just need to find time.

In the meantime, you can unblock yourselves by wrapping the updates that suspend in await act(async () => { ... }). The passed callback to act must be async in those cases.

[flq]

We have about 3'000 frontend tests - while "only" 10% are currently failing, I'm afraid we'll have to wait and see what happens next. I sill find it weird though that a "render" call on a component tree that starts being suspended seems to starve to death with the children never being rendered.

[0xc14m1z]

Thanks @eps1lon for taking care of this.

We're going to postpone the upgrade because we have around 300 tests failing because of this issue.
Some of them assert against the fallback, so they'll fail anyway when wrapping the suspended updates with the async act.

The workaround would have to be reverted once the issue is fixed.

[centraldogma99]

@0xc14m1z What were the common points of the failing tests?

[tpict]

We're seeing a lot of failures where we have hooks that suspend on the initial render e.g. Apollo's useSuspenseQuery.

Will we be required to wrap render calls in act to handle this?

[flq]

@centraldogma99 we‘re seeing tests that hang in staying suspended - the asynchronous call is done, but the Suspense boundary will never render its children. Wrapping render in act will cause the boundary to render its children, however, the suspense placeholder is not observable by the test anymore.

[0xc14m1z]

Is there any update here? Is there something that can be done to help resolving this issue?

[wojtekmaj]

I have 1000s of unit tests, all using a custom wrapper around render() to automatically add <Suspense> as we use Jotai store and most components just access the required atoms directly using useAtomValue. This is basically the setup we're using:

function wrap({ children }: { children: React.ReactNode }) {
  const store = createStore();

  return (
    <JotaiProvider store={store}>
      <Suspense fallback={<div data-testid="suspense" />}>
        {children}
      </Suspense>
    </JotaiProvider>
  );
}

export function renderWrapped(ui: React.ReactNode, options?: RenderOptions) {
  return render(ui, { ...options, wrapper: wrap });
}

export async function waitForSuspense() {
  const suspense = screen.queryByTestId('suspense');

  if (suspense) {
    await waitForElementToBeRemoved(() => screen.queryByTestId('suspense'));
  }
}

We're NOT having a good time 😅

[tpict]

Is there a way for us to replicate the proposed new behavior while the relevant PRs are in flight? I'm in a similar position to wojtekmaj and it's the last item blocking our upgrade to React 19.

[christopher1986]

I think we should move forwards with the open PR we have for await act.. Wdyt?

That's the plan for January. Just need to find time.

In the meantime, you can unblock yourselves by wrapping the updates that suspend in await act(async () => { ... }). The passed callback to act must be async in those cases.

Does this also apply to convenience methods such as fireEvent if they trigger a re-render? I read somewhere that the React testing library already integrated act with its APIs. So in most cases, we do not need to wrap render and fireEvent in act.

However since upgrading to React 19 and using Suspense I noticed that when a re-render happens due to fireEvent I need to wrap it with act() otherwise I also get a warning informing act is needed.