Proposal: global.IS_REACT_ACT_ENVIRONMENT

[acdlite]

This proposal has been implemented and is now available in the latest React 18 alphas.

Note: This may or may not be the final name. Will likely go through a round of bikeshedding.

tl;dr

• Replaces clowny typeof jest === 'undefined' heuristic
• Configured by your testing framework
• "Not wrapped in act" warnings only fire when it actually makes sense (so, not in end-to-end tests)

Background: Why does React warn if you don't wrap updates with act?

act is the API we use to flush React's asynchronous task queues at the end of some scope of work. Usually, an act scope corresponds to a browser event like a click or a network response handler:

// A click updates React
await act(() => simulateClick());
// Assert on React tree here...

We introduced the act API alongside hooks, because useEffect was the first React API to schedule asynchronous work. We call these "passive" effects, and they fire after the browser has painted.

If you were to test a component that contains a useEffect, but you didn't use act in your test, then the passive effects would not fire, and your tests would not match production behavior.

In concurrent React, it's not just passive effects — all work happens in an async task (with the exception of flushSync), so the problem is more pronounced. You probably wouldn't forget to use act in the normal case — otherwise, React wouldn't update the screen at all. But it's feasible that you would forget to wrap, say, a mocked network response that happens to resolve a Suspense promise.

To prevent this mistake, React fires a warning if it receives an update that hasn't been wrapped with act:

An update to SomeComponent ran an effect, but was not wrapped in act(...)

React only fires this warning if detects that you're in a testing environment. Here's where things get messy...

act is not the right API for all tests

act is designed for tests where you know exactly which event queues are relevant and you can control them, usually with mocking. In addition to user interactions, common examples include timers and network events:

// A queued timer updates React
await act(() => runTimers());
// Assert on React tree here...

// A request resolves a Suspense promise
await act(() => resolveMockNetworkRequest());
// Assert on React tree here...

It's not designed for tests where you poll until something changes, like end-to-end (e2e) tests, or React Testing Library's waitFor method:

// Does this update React? Does it perform a network request? Who knows!
doAThing();

// But we do know the output
await pollUIUntilTextAppears('The thing succeeded!')

In an e2e test, instead of mocking your task queues, you run your code in something resembling a "real" browser environment, and wait until the UI matches what you expect.

The mechanism we currently use to decide whether to warn is pretty clowny: we check if jest is globally defined. This has some pretty obvious flaws — for example, tests that don't use Jest don't get any warnings at all.

Another flaw is, even if you do use Jest, you might be writing an e2e test. But doesn't make sense to use act in an e2e test. So why does React warn about it?

There are other tests where act isn't necessary, like our tests that mock the Scheduler package. React shouldn't warn about those, either.

So we need new a new strategy. We added the global jest check as a temporary hack to unblock ourselves, but never got around to replacing it with something better.

Make act an opt-in testing pattern

My proposal is to provide an API for users to tell React that they are writing act-style tests. I don't know what to call it yet, but let's go with this for now:

global.IS_REACT_ACT_ENVIRONMENT

React would read this global to decide whether to fire act warnings.

Users typically would not set this directly; it'd be configured somewhere in your testing infra, like a Jest plugin or an assertion library.

For example, you might enable act warnings for the scope of a single function:

const prev = global.IS_REACT_ACT_ENVIRONMENT;
global.IS_REACT_ACT_ENVIRONMENT = true;
try {
  await scope();
} finally {
  global.IS_REACT_ACT_ENVIRONMENT = prev;
}

You could also do the inverse: disable act warnings for the scope of a single test.

Or you might enable act warnings for all the tests in a file:

let prev;
beforeAll(() => {
  const prev = global.IS_REACT_ACT_ENVIRONMENT;
  global.IS_REACT_ACT_ENVIRONMENT = true;
});
afterAll(() => {
  global.IS_REACT_ACT_ENVIRONMENT = prev;
});

Because you have to opt into this configuration, tests that don't use act won't trigger spurious warnings.

What if users do use act but forget to opt into warnings?

We'll warn about it :)

If you do use act, but IS_REACT_ACT_ENVIRONMENT isn't true, then we will warn you to update your testing infra.

Except in legacy roots (ReactDOM.render), since otherwise we'd break existing tests.

[eps1lon]

Thanks for writing this up. The background was helpful to understand the warning better for React 18 specifically.

I think in the end almost every usage would use the beforeAll/AfterAll pattern.

That being said, I was hoping this proposal addresses the issues with fake vs real timers and act warnings.

If you do use act, but IS_REACT_ACT_ENVIRONMENT isn't true, then we will warn you to update your testing infra.

React Testing Library wraps all the relevant APIs in act() (render, unmount, firing events etc). With your proposal we can't use the same API for fake and real timers. This is a problem because we ultimately have no 100% accurate way to check whether we run with fake or real timers. This was painful for us during the jest 26 - 27 migration.

So assuming this proposal makes it through, let's look at a common testing pattern with React Testing Library:

Please ignore the specific implementation for data-fetching. We just want something that loads something on click.

import { Fragment, useEffect, useState } from 'react';
import { fireEvent, render, screen } from '@testing-library/react';

it('displays content when clicked', async () => {
   function App() {
     const [showContent, setShowContent] = useState(false);

     const [content, setContent] = useState(false);
     useEffect(() => {
       if (showContent) {
         // just mocking some fetch()
         setTimeout(() => {
           setContent('fetched content')
         }, 1000)
       }
     }, [showContent])

     return <Fragment><button onClick={() => setShowContent(true)} />{content}</Fragment>
   }

   render(<App />);

   // This schedules an effect
   // Triggers no warning since Testing Library wraps this in `act()`
   fireEvent.click(getByRole('button'));

   await waitFor(() => expect(screen.getByText('fetched content')).toBeVisible());
});

Historically, this worked with real timers and fake timers. Every RTL API was wrapped in act() and waitFor implementation addressed real vs jest fake timers. Fake timers outside of Jest were simply not supported by waitFor.

So let's think about the implementation with different timers:

real timers
render would need to set IS_REACT_ACT_ENVIRONMENT so that it can stay synchronous by wrapping with act()
fireEvent.* would need to set IS_REACT_ACT_ENVIRONMENT so that we can use act() (otherwise we would need an additional waitFor to assert on scheduled effects by that event)
waitFor has to disable IS_REACT_ACT_ENVIRONMENT because we can't wrap everything in act. The update would only be flushed after we exit waitFor but the condition to exit waitFor needs updates to be flushed.

fake timers
Every API runs with IS_REACT_ACT_ENVIRONMENT. Tests work as expected (already working with our latest alpha).

The problem is that now every API needs to be able to detect real vs fake timers not just waitFor.

It all seems like we trade one warning for another warning.

Though I may just argue against having to do all this work. I don't think I can fully grasp all the edge cases we may or may not hit. So shipping it behind a flag so that I can play around with it in different repos would help me personally see if this proposal works.

At least before I could avoid them since I wasn't using Jest and just opted-in via global.jest = null. But it seems that now everybody will see one kind of act-related warning.

Regarding the implementation: I would prefer setting this value in the React module itself (e.g. React.reactActEnvironment(boolean). We already need a single instance of React so it makes sense to me to set it there. Negotiating which "global" we mean might be too brittle.

[acdlite]

Thanks for the example! I think I'm missing some context, though, that would explain why you need to detect fake timers in the new proposal. I can see why that's necessary today — to check whether the waitFor scope needs to be wrapped with act, because otherwise you'll get spurious warnings. But since the new proposal gives you a way to disable the act warning inside the waitFor scope, I wonder what other reason you need to detect fake timers.

Would this implementation work?

• APIs that trigger render and click automatically wraps with act. It sets IS_REACT_ACT_ENVIRONMENT to true before the act call, and sets it back to the previous value when act exits.
• waitFor does this inverse: it sets IS_REACT_ACT_ENVIRONMENT to false until the end of the scope, then restores the previous value. When the timer (or any other I/O) resolves and schedules an update, React doesn't warn.

Regarding the implementation: I would prefer setting this value in the React module itself (e.g. React.reactActEnvironment(boolean). We already need a single instance of React so it makes sense to me to set it there. Negotiating which "global" we mean might be too brittle.

We considered that API, and you're right that we already require a single instance of React. We went with a global instead because 1) it avoids having to deal with a dev-only export, which are tricky to do with ES modules 2) we expect most people to enable this value via a plugin, like a Jest environment. If that is later followed by a resetModules call (or the equivalent), and the config lives inside module state, you would have to set the config again 3) we have precedent for this with how DevTools injects its runtime with a global 4) it's easier to revert later; like if we reverse course and decide to remove the act warnings entirely, we don't have to keep a no-op method around until the next major release cycle.

[eps1lon]

Would this implementation work?

• APIs that trigger render and click automatically wraps with act. It sets IS_REACT_ACT_ENVIRONMENT to true before the act call, and sets it back to the previous value when act exits.
• waitFor does this inverse: it sets IS_REACT_ACT_ENVIRONMENT to false until the end of the scope, then restores the previous value. When the timer (or any other I/O) resolves and schedules an update, React doesn't warn.

I think this does work. Maybe I was just having trouble with the name since we call it "environment" but an environment is usually something that doesn't change during the lifetime of a test. But now we treat it as something that does change during the lifetime of a test depending on the testing API we use.

It's more like a SCOPE_WONT_WAIT_FOR_UPDATES_TO_BE_FLUSHED. For example, render is sync so we need act to flush all updates. But waitFor polls directly for the updates to be flushed so it doesn't need act.

This all just gets exponentially complex since we want to support all React majors and real/jest fake timers. Dropping support for React 17 is viable for us but makes teaching harder since we can no longer say "just install @testing-library/react".

We went with a global instead because [...]

Understandable. The issues with finding the right "global" are just theoretical at this point.

[acdlite]

Agree the name is a bit confusing, we went back and forth on a few options but couldn't think of anything better. We'll bikeshed again before releasing. Would love to hear your suggestions if you have them. Though I'm not too worried about it ultimately, since we don't expect developers to set the flag manually (unless you're the maintainer of a testing framework).

This all just gets exponentially complex since we want to support all React majors and real/jest fake timers. Dropping support for React 17 is viable for us but makes teaching harder

If you want to support 17 and 18 simultaneously, one possible strategy could be, whenever you set IS_REACT_ACT_ENVIRONMENT to false (waitFor), also set the jest global to undefined/null. And then restore it at the end. This is nice because it works for all types of I/O, not just timers, and it's the same implementation that you use in 18 but with a different global. In a future release, when you drop support for React 17, you would just delete the lines that override jest.

The only potential issue I can think of is that it would break tests that call jest.runAllTimers inside waitFor, but you're not supposed to do that regardless. Perhaps there are other flaws I haven't considered. What do you think?

[eps1lon]

The only potential issue I can think of is that it would break tests that call jest.runAllTimers inside waitFor, but you're not supposed to do that regardless. Perhaps there are other flaws I haven't considered. What do you think?

We actually do call jest.advanceTimersByTime() during waitFor if we think that we're running with jest fake timers. I'd have to check if we can just copy the relevant methods before setting jest = null.

Though I don't feel comfortable just deleting jest even if temporarily. Simply because I don't know if there are valid use cases where you do need access to the Jest object in waitFor. And even if there aren't, then there may be uses cases in the future with new APIs on the Jest object.

It is the easiest path since it also prevents another kind of mistake where people switched between fake and real timers during waitFor. The problem is just that this mistake leads to a confusing error message ("Uncaught TypeError: Cannot read properties of null").

Can we just keep the old behavior if we think we're running with React pre 18 (e.g. React.unstable_act !== undefined or React.version === undefined || /^(16|17)\./.test(React.version))?

[acdlite]

Yeah that’s fine, was just thinking of ways to possibly reduce maintenance burden but I can see how that introduces its own risks

[acdlite]

This proposal has been implemented and is now available in the latest React 18 alphas

[henryqdineen]

Replaces clowny typeof jest === 'undefined' heuristic

We noticed that this heuristic is still in place. Was this a mistake? Thanks.