feat: support for react suspense

src/__tests__/react-suspense.test.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import TestRenderer, { type ReactTestRenderer } from 'react-test-renderer';
+
+import { configure, renderAsync, screen, within } from '..';
+
+const isReact19 = React.version.startsWith('19.');
+const testGateReact19 = isReact19 ? test : test.skip;
+
+configure({
+  asyncUtilTimeout: 5000,
+});
+
+function wait(delay: number) {
+  return new Promise<void>((resolve) =>
+    setTimeout(() => {
+      resolve();
+    }, delay),
+  );
+}
+
+function Suspending<T>({ promise }: { promise: Promise<T> }) {
+  React.use(promise);
+  return <View testID="view" />;
+}
+
+testGateReact19('render supports components which can suspend', async () => {
+  await renderAsync(
+    <View>
+      <React.Suspense fallback={<View testID="fallback" />}>
+        <Suspending promise={wait(100)} />
+      </React.Suspense>
+    </View>,
+  );
+
+  expect(screen.getByTestId('fallback')).toBeOnTheScreen();
+  expect(await screen.findByTestId('view')).toBeOnTheScreen();
+});
+
+testGateReact19('react test renderer supports components which can suspend', async () => {
+  let renderer: ReactTestRenderer;
+
+  // eslint-disable-next-line require-await
+  await React.act(async () => {
+    renderer = TestRenderer.create(
+      <View>
+        <React.Suspense fallback={<View testID="fallback" />}>
+          <Suspending promise={wait(100)} />
+        </React.Suspense>
+      </View>,
+    );
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const view = within(renderer!.root);
+
+  expect(view.getByTestId('fallback')).toBeDefined();
+  expect(await view.findByTestId('view')).toBeDefined();
+});

src/pure.ts

@@ -2,6 +2,7 @@ export { default as act } from './act';
 export { default as cleanup } from './cleanup';
 export { default as fireEvent } from './fire-event';
 export { default as render } from './render';
+export { default as renderAsync } from './render-async';
 export { default as waitFor } from './wait-for';
 export { default as waitForElementToBeRemoved } from './wait-for-element-to-be-removed';
 export { within, getQueriesForElement } from './within';
@@ -19,6 +20,7 @@ export type {
   RenderResult as RenderAPI,
   DebugFunction,
 } from './render';
+export type { RenderAsyncOptions, RenderAsyncResult } from './render-async';
 export type { RenderHookOptions, RenderHookResult } from './render-hook';
 export type { Config } from './config';
 export type { UserEventConfig } from './user-event';

src/render-act.ts

@@ -18,3 +18,19 @@ export function renderWithAct(
   // @ts-expect-error: `act` is synchronous, so `renderer` is already initialized here
   return renderer;
 }
+
+export async function renderWithAsyncAct(
+  component: React.ReactElement,
+  options?: Partial<TestRendererOptions>,
+): Promise<ReactTestRenderer> {
+  let renderer: ReactTestRenderer;
+
+  // eslint-disable-next-line require-await
+  await act(async () => {
+    // @ts-expect-error `TestRenderer.create` is not typed correctly
+    renderer = TestRenderer.create(component, options);
+  });
+
+  // @ts-expect-error: `renderer` is already initialized here
+  return renderer;
+}

src/render-async.tsx

@@ -0,0 +1,131 @@
+import * as React from 'react';
+import type {
+  ReactTestInstance,
+  ReactTestRenderer,
+  TestRendererOptions,
+} from 'react-test-renderer';
+
+import act from './act';
+import { addToCleanupQueue } from './cleanup';
+import { getConfig } from './config';
+import { getHostSelves } from './helpers/component-tree';
+import type { DebugOptions } from './helpers/debug';
+import { debug } from './helpers/debug';
+import { renderWithAsyncAct } from './render-act';
+import { setRenderResult } from './screen';
+import { getQueriesForElement } from './within';
+
+export interface RenderAsyncOptions {
+  /**
+   * Pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating
+   * reusable custom render functions for common data providers.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  wrapper?: React.ComponentType<any>;
+
+  /**
+   * Set to `false` to disable concurrent rendering.
+   * Otherwise `render` will default to concurrent rendering.
+   */
+  // TODO: should we assume concurrentRoot is true for react suspense?
+  concurrentRoot?: boolean;
+
+  createNodeMock?: (element: React.ReactElement) => unknown;
+}
+
+export type RenderAsyncResult = ReturnType<typeof renderAsync>;
+
+/**
+ * Renders test component deeply using React Test Renderer and exposes helpers
+ * to assert on the output.
+ */
+export default async function renderAsync<T>(
+  component: React.ReactElement<T>,
+  options: RenderAsyncOptions = {},
+) {
+  const { wrapper: Wrapper, concurrentRoot, ...rest } = options || {};
+
+  const testRendererOptions: TestRendererOptions = {
+    ...rest,
+    // @ts-expect-error incomplete typing on RTR package
+    unstable_isConcurrent: concurrentRoot ?? getConfig().concurrentRoot,
+  };
+
+  const wrap = (element: React.ReactElement) => (Wrapper ? <Wrapper>{element}</Wrapper> : element);
+  const renderer = await renderWithAsyncAct(wrap(component), testRendererOptions);
+  return buildRenderResult(renderer, wrap);
+}
+
+function buildRenderResult(
+  renderer: ReactTestRenderer,
+  wrap: (element: React.ReactElement) => React.JSX.Element,
+) {
+  const update = updateWithAsyncAct(renderer, wrap);
+  const instance = renderer.root;
+
+  // TODO: test this
+  const unmount = async () => {
+    // eslint-disable-next-line require-await
+    await act(async () => {
+      renderer.unmount();
+    });
+  };
+
+  addToCleanupQueue(unmount);
+
+  const result = {
+    ...getQueriesForElement(instance),
+    update,
+    unmount,
+    rerender: update, // alias for `update`
+    toJSON: renderer.toJSON,
+    debug: makeDebug(renderer),
+    get root(): ReactTestInstance {
+      return getHostSelves(instance)[0];
+    },
+    UNSAFE_root: instance,
+  };
+
+  // Add as non-enumerable property, so that it's safe to enumerate
+  // `render` result, e.g. using destructuring rest syntax.
+  Object.defineProperty(result, 'container', {
+    enumerable: false,
+    get() {
+      throw new Error(
+        "'container' property has been renamed to 'UNSAFE_root'.\n\n" +
+          "Consider using 'root' property which returns root host element.",
+      );
+    },
+  });
+
+  setRenderResult(result);
+
+  return result;
+}
+
+// TODO: test this
+function updateWithAsyncAct(
+  renderer: ReactTestRenderer,
+  wrap: (innerElement: React.ReactElement) => React.ReactElement,
+) {
+  return async function (component: React.ReactElement) {
+    // eslint-disable-next-line require-await
+    await act(async () => {
+      renderer.update(wrap(component));
+    });
+  };
+}
+
+export type DebugFunction = (options?: DebugOptions) => void;
+
+function makeDebug(renderer: ReactTestRenderer): DebugFunction {
+  function debugImpl(options?: DebugOptions) {
+    const { defaultDebugOptions } = getConfig();
+    const debugOptions = { ...defaultDebugOptions, ...options };
+    const json = renderer.toJSON();
+    if (json) {
+      return debug(json, debugOptions);
+    }
+  }
+  return debugImpl;
+}