feat: necessary api changes for React 19 compatibility (#10)

BREAKING CHANGE: This release has to break some old APIs to stay compatible with React 19.

\#\# `render` is now `async` and should be `await`ed

This is the core change - due to the impementation of sibling prerendering on the React side, rendering has become more `async` and tests that interacted with `render` in a synchronous fashion would end up with not-resolving suspense boundaries.

Please adjust your tests accordingly:

```diff
  const {takeRender, render} = createRenderStream({ /* ... */ })
-  const utils = render(<Counter />)
+  const utils = await render(<Counter />)
```

\#\# enforcing of `IS_REACT_ACT_ENVIRONMENT == false`

In combination with [issues we have have seen in the past](facebook/react#29855), we have deduced that the testing approach of this library only really works in a "real-world" scenario, not in an `act` environment.

As a result, we will now throw an error if you try to use it in an environment where `IS_REACT_ACT_ENVIRONMENT` is truthy.

We are shipping a new tool, `disableActEnvironment` to prepare your environment for the duration of a test in a safe manner.

This helper can either be used with explicit resource management using the `using` keyword:

```ts
test('my test', () => {
  using _disabledAct = disableActEnvironment()

  // your test code here

  // as soon as this scope is left, the environment will be cleaned up
})
```

of by manually calling `cleanup`:

```ts
test('my test', () => {
  const {cleanup} = disableActEnvironment()

  try {
    // your test code here
  } finally {
    cleanup()
  }
})
```

This function does not only adjust your `IS_REACT_ACT_ENVIRONMENT` value, but it will also temporarily adjust the `@testing-library/dom` configuration in a way so that e.g. calls to `userEvent` will not automatically be wrapped in `act`.

Of course you can also use this tool on a per-file basis instead of a per-test basis, but keep in mind that doing so will break any React Testing Library tests that might be in the same file.

\#\# `render` is now it's own implementation

Previously, we used the `render` function of React Testing Library, but with the new restrictions this is no longer possible and we are shipping our own implementation.

As a result, some less-common options are not supported in the new implementation.
If you have a need for these, please let us know!

* `hydrate` was removed
* `legacyRoot` was removed. If you are using React 17, it will automatically switch to `ReactDOM.render`, otherwise we will use `createRoot`

> [!CAUTION]
> React 17 does not look for `IS_REACT_ACT_ENVIRONMENT` to determine if it is running in an `act`-environment, but rather `typeof jest !== "undefined"`.
> If you have to test React 17, we recommend to patch it with a [`patch-package` patch](https://github.com/apollographql/apollo-client/blob/8a4738a8ad7284d247513671628a4ac5917e104c/patches/react-dom-17+17.0.2.patch)

\#\#  `renderToRenderStream` was removed

As you now have to `await` the `render` call, `renderToRenderStream` had no real value anymore.

Where previously, the second line of
```js
const renderStream = renderToRenderStream(<Component />, combinedOptions)
// this was optional in the past
const utils = await renderStream.renderResultPromise
```
could be omitted and could save you some code, now that second line would become required.

This now was not any shorter than calling `createRenderStream` and `renderStream.render` instead, and as both of these APIs now did the same thing in a different fashion, this would lead to confusion to no more benefit, so the API was removed.

Author: phryneas

README.md

@@ -2,9 +2,9 @@
 
 ## What is this library?
 
-This library allows you to make render-per-render assertions on your React
-components and hooks. This is usually not necessary, but can be highly
-beneficial when testing hot code paths.
+This library allows you to make committed-render-to-committed-render assertions
+on your React components and hooks. This is usually not necessary, but can be
+highly beneficial when testing hot code paths.
 
 ## Who is this library for?
 
@@ -36,7 +36,7 @@ test('iterate through renders with DOM snapshots', async () => {
   const {takeRender, render} = createRenderStream({
     snapshotDOM: true,
   })
-  const utils = render(<Counter />)
+  const utils = await render(<Counter />)
   const incrementButton = utils.getByText('Increment')
   await userEvent.click(incrementButton)
   await userEvent.click(incrementButton)
@@ -58,36 +58,14 @@ test('iterate through renders with DOM snapshots', async () => {
 })
 ```
 
-### `renderToRenderStream` as a shortcut for `createRenderStream` and calling `render`
-
-In every place you would call
-
-```js
-const renderStream = createRenderStream(options)
-const utils = renderStream.render(<Component />, options)
-```
-
-you can also call
-
-```js
-const renderStream = renderToRenderStream(<Component />, combinedOptions)
-// if required
-const utils = await renderStream.renderResultPromise
-```
-
-This might be shorter (especially in cases where you don't need to access
-`utils`), but keep in mind that the render is executed **asynchronously** after
-calling `renderToRenderStream`, and that you need to `await renderResultPromise`
-if you need access to `utils` as returned by `render`.
-
 ### `renderHookToSnapshotStream`
 
 Usage is very similar to RTL's `renderHook`, but you get a `snapshotStream`
 object back that you can iterate with `takeSnapshot` calls.
 
 ```jsx
 test('`useQuery` with `skip`', async () => {
-  const {takeSnapshot, rerender} = renderHookToSnapshotStream(
+  const {takeSnapshot, rerender} = await renderHookToSnapshotStream(
     ({skip}) => useQuery(query, {skip}),
     {
       wrapper: ({children}) => <Provider client={client}>{children}</Provider>,
@@ -105,7 +83,7 @@ test('`useQuery` with `skip`', async () => {
     expect(result.data).toEqual({hello: 'world 1'})
   }
 
-  rerender({skip: true})
+  await rerender({skip: true})
   {
     const snapshot = await takeSnapshot()
     expect(snapshot.loading).toBe(false)
@@ -146,7 +124,7 @@ test('`useTrackRenders` with suspense', async () => {
   }
 
   const {takeRender, render} = createRenderStream()
-  render(<App />)
+  await render(<App />)
   {
     const {renderedComponents} = await takeRender()
     expect(renderedComponents).toEqual([App, LoadingComponent])
@@ -179,7 +157,7 @@ test('custom snapshots with `replaceSnapshot`', async () => {
   const {takeRender, replaceSnapshot, render} = createRenderStream<{
     value: number
   }>()
-  const utils = render(<Counter />)
+  const utils = await render(<Counter />)
   const incrementButton = utils.getByText('Increment')
   await userEvent.click(incrementButton)
   {
@@ -215,16 +193,14 @@ test('assertions in `onRender`', async () => {
     )
   }
 
-  const {takeRender, replaceSnapshot, renderResultPromise} =
-    renderToRenderStream<{
-      value: number
-    }>({
-      onRender(info) {
-        // you can use `expect` here
-        expect(info.count).toBe(info.snapshot.value + 1)
-      },
-    })
-  const utils = await renderResultPromise
+  const {takeRender, replaceSnapshot, utils} = await renderToRenderStream<{
+    value: number
+  }>({
+    onRender(info) {
+      // you can use `expect` here
+      expect(info.count).toBe(info.snapshot.value + 1)
+    },
+  })
   const incrementButton = utils.getByText('Increment')
   await userEvent.click(incrementButton)
   await userEvent.click(incrementButton)
@@ -247,7 +223,7 @@ This library adds to matchers to `expect` that can be used like
 
 ```tsx
 test('basic functionality', async () => {
-  const {takeRender} = renderToRenderStream(<RerenderingComponent />)
+  const {takeRender} = await renderToRenderStream(<RerenderingComponent />)
 
   await expect(takeRender).toRerender()
   await takeRender()
@@ -285,17 +261,46 @@ await expect(snapshotStream).toRerender()
 > [!TIP]
 >
 > If you don't want these matchers not to be automatically installed, you can
-> import from `@testing-library/react-render-stream` instead.
+> import from `@testing-library/react-render-stream/pure` instead.  
+> Keep in mind that if you use the `/pure` import, you have to call the
+> `cleanup` export manually after each test.
+
+## Usage side-by side with `@testing-library/react` or other tools that use `act` or set `IS_REACT_ACT_ENVIRONMENT`
 
-## A note on `act`.
+This library should not be used with `act`, and it will throw an error if
+`IS_REACT_ACT_ENVIRONMENT` is `true`.
 
-You might want to avoid using this library with `act`, as `act`
-[can end up batching multiple renders](https://github.com/facebook/react/issues/30031#issuecomment-2183951296)
-into one in a way that would not happen in a production application.
+React Testing Library sets `IS_REACT_ACT_ENVIRONMENT` to `true` globally, and
+wraps some helpers like `userEvent.click` in `act` calls.  
+To use this library side-by-side with React Testing Library, we ship the
+`disableActEnvironment` helper to undo these changes temporarily.
 
-While that is convenient in a normal test suite, it defeats the purpose of this
-library.
+It returns a `Disposable` and can be used together with the
+[`using` keyword](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)
+to automatically clean up once the scope is left:
 
-Keep in mind that tools like `userEvent.click` use `act` internally. Many of
-those calls would only trigger one render anyways, so it can be okay to use
-them, but avoid this for longer-running actions inside of `act` calls.
+```ts
+test('my test', () => {
+  using _disabledAct = disableActEnvironment()
+
+  // your test code here
+
+  // as soon as this scope is left, the environment will be cleaned up
+})
+```
+
+If you cannot use `using`, you can also manually call the returned `cleanup`
+function. We recommend using `finally` to ensure the act environment is cleaned
+up if your test fails, otherwise it could leak between tests:
+
+```ts
+test('my test', () => {
+  const {cleanup} = disableActEnvironment()
+
+  try {
+    // your test code here
+  } finally {
+    cleanup()
+  }
+})
+```

package.json

@@ -83,8 +83,8 @@
     "pkg-pr-new": "^0.0.29",
     "prettier": "^3.3.3",
     "publint": "^0.2.11",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "19.0.0-rc.1",
+    "react-dom": "19.0.0-rc.1",
     "react-error-boundary": "^4.0.13",
     "ts-jest-resolver": "^2.0.1",
     "tsup": "^8.3.0",

src/__testHelpers__/useShim.js

@@ -1,3 +1,5 @@
+import * as React from 'react'
+
 /* eslint-disable default-case */
 /* eslint-disable consistent-return */
 function isStatefulPromise(promise) {
@@ -33,7 +35,7 @@ function wrapPromiseWithState(promise) {
  * @param {Promise<T>} promise
  * @returns {T}
  */
-export function __use(promise) {
+function _use(promise) {
   const statefulPromise = wrapPromiseWithState(promise)
   switch (statefulPromise.status) {
     case 'pending':
@@ -44,3 +46,5 @@ export function __use(promise) {
       return statefulPromise.value
   }
 }
+
+export const __use = /** @type {{use?: typeof _use}} */ (React).use || _use

src/__testHelpers__/withDisabledActWarnings.ts

@@ -1,10 +1,10 @@
 /* eslint-disable no-await-in-loop */
 /* eslint-disable @typescript-eslint/no-unnecessary-condition */
 import {EventEmitter} from 'node:events'
+import {scheduler} from 'node:timers/promises'
 import {test, expect} from '@jest/globals'
 import {renderHookToSnapshotStream} from '@testing-library/react-render-stream'
 import * as React from 'react'
-import {withDisabledActWarnings} from '../__testHelpers__/withDisabledActWarnings.js'
 
 const testEvents = new EventEmitter<{
   rerenderWithValue: [unknown]
@@ -16,7 +16,7 @@ function useRerenderEvents(initialValue: unknown) {
     onChange => {
       const cb = (value: unknown) => {
         lastValueRef.current = value
-        withDisabledActWarnings(onChange)
+        onChange()
       }
       testEvents.addListener('rerenderWithValue', cb)
       return () => {
@@ -30,11 +30,11 @@ function useRerenderEvents(initialValue: unknown) {
 }
 
 test('basic functionality', async () => {
-  const {takeSnapshot} = renderHookToSnapshotStream(useRerenderEvents, {
+  const {takeSnapshot} = await renderHookToSnapshotStream(useRerenderEvents, {
     initialProps: 'initial',
   })
   testEvents.emit('rerenderWithValue', 'value')
-  await Promise.resolve()
+  await scheduler.wait(10)
   testEvents.emit('rerenderWithValue', 'value2')
   {
     const snapshot = await takeSnapshot()
@@ -59,7 +59,7 @@ test.each<[type: string, initialValue: unknown, ...nextValues: unknown[]]>([
   ['null/undefined', null, undefined, null],
   ['undefined/null', undefined, null, undefined],
 ])('works with %s', async (_, initialValue, ...nextValues) => {
-  const {takeSnapshot} = renderHookToSnapshotStream(useRerenderEvents, {
+  const {takeSnapshot} = await renderHookToSnapshotStream(useRerenderEvents, {
     initialProps: initialValue,
   })
   for (const nextValue of nextValues) {