Introduction

The official React testing pattern with await act(async () => ...) works because it gives React a chance to process all queued updates before the test makes assertions. act is the "flush React work" boundary, and await matters because some of that work is triggered by promises, timers, or async effects rather than finishing immediately.

What act Actually Guarantees

React batches updates and applies them across renders, effects, and microtasks. In a real browser, users naturally wait while those updates finish. In a test, the code often runs much faster than the UI lifecycle, so an assertion can happen before React has finished the work.

act tells React, "everything triggered inside this scope should be processed before I continue." That is why React warns when state updates happen outside an act boundary. The warning is not about syntax style. It is about test timing.

Why the async and await Parts Matter

For synchronous updates, plain act(() => { ... }) is enough. But if the code inside the test causes a promise to resolve later, React cannot flush that future work unless the test waits for it.

That is why the async form exists:

1import { act } from "react-dom/test-utils";
2
3await act(async () => {
4  // trigger code that eventually causes state updates
5});

The await keeps the test paused until the promise chain settles and React has had a chance to commit the resulting updates. Without await, the test can move on too early.

A Concrete Example

Consider a component that loads data on mount:

1import React, { useEffect, useState } from "react";
2
3export function UserCard({ loadUser }) {
4  const [name, setName] = useState("loading");
5
6  useEffect(() => {
7    let active = true;
8
9    loadUser().then(user => {
10      if (active) {
11        setName(user.name);
12      }
13    });
14
15    return () => {
16      active = false;
17    };
18  }, [loadUser]);
19
20  return <div>{name}</div>;
21}

A manual test can wrap the render in async act:

1import React from "react";
2import { createRoot } from "react-dom/client";
3import { act } from "react-dom/test-utils";
4import { UserCard } from "./UserCard";
5
6test("shows loaded user name", async () => {
7  const container = document.createElement("div");
8  const root = createRoot(container);
9  const loadUser = () => Promise.resolve({ name: "Ada" });
10
11  await act(async () => {
12    root.render(<UserCard loadUser={loadUser} />);
13  });
14
15  expect(container.textContent).toBe("Ada");
16});

This works because the render triggers an effect, the effect starts a promise, the promise resolves, setState runs, and act keeps flushing until React has settled that chain.

Why It Often Looks Like Magic

It feels surprising because the promise resolution does not appear directly in the assertion code. But act is not guessing. It is observing React's scheduled updates and waiting for them to finish within the async boundary.

That said, act is not a universal "wait for anything" tool. It helps with work that React knows about. If your test depends on external timers, mocked network layers, or custom event loops, those may still need to be advanced or awaited separately.

Testing Library Often Wraps This for You

If you use React Testing Library, many user interactions and async helpers already wrap updates in act. That is why code like await screen.findByText(...) often works without a manual act block.

For example:

1import { render, screen } from "@testing-library/react";
2import { UserCard } from "./UserCard";
3
4test("shows loaded user name", async () => {
5  render(<UserCard loadUser={() => Promise.resolve({ name: "Ada" })} />);
6  expect(await screen.findByText("Ada")).toBeInTheDocument();
7});

This is conceptually doing the same kind of waiting, just through a higher-level testing API.

Common Pitfalls

The most common mistake is forgetting await on async act. Without it, the test continues before the async React work settles.

Another issue is assuming act waits for unrelated async work automatically. It coordinates React updates, not every promise in the universe.

Developers also wrap everything in manual act even when a testing library helper already does it. That adds noise without adding correctness.

Summary

• 'act tells React tests to flush scheduled UI updates before assertions run.'
• The async form is needed when those updates are triggered through promises or effects.
• 'await act(async () => ...) works because it keeps the test paused until React settles the work inside that boundary.'
• React Testing Library often provides this behavior through higher-level helpers such as findByText.
• Use act for React-managed updates, but remember that external async mechanisms may still need separate control.