feat: add renderAsync for testing async React Server Components

[aurorascharff]

What:

Add renderAsync — a first-class API for testing async React Server Components and components using React 19's use() API.

Why:

React 19's client-side renderer (react-dom/client) does not support async function components — they only work with the server renderer. This has been a major pain point for the community (#1209), forcing projects to either pin to a specific RC version of React (19.0.0-rc-380f5d67-20241113), write custom render helpers, or abandon unit testing RSCs in favor of E2E tests.

That RC version worked because its fiber reconciler had implicit use() behavior for async components — when it encountered a Promise return value from a function component, it suspended at the nearest Suspense boundary. This was removed before the stable React 19 release. renderAsync replicates that behavior in userland.

How:

Two-phase approach:

1. Pre-resolution (resolveElement): Recursively walks the JSX element tree, calls async function components with await, and replaces them with their resolved output before React ever sees them. Walks all props — not just children — so async components passed as e.g. sidebar, header, or fallback props are also resolved. Handles nested async components, siblings, fragments, and any server/client component tree.

2. Suspense + act(): Wraps the resolved tree in a <Suspense> boundary and renders inside await act(async () => ...), so components using use(promise) suspend and resolve correctly.

The returned result matches render() except rerender is async (it also pre-resolves and flushes suspensions).

Note: This PR was authored with AI assistance (Cursor + Claude). I'm not deeply experienced with RTL internals, so I'd especially appreciate feedback on whether the approach and conventions are right. Happy to iterate.

Checklist:

• Documentation added to the
  docs site
• Tests
• TypeScript definitions updated
• Ready to be merged

24 tests covering: simple/nested/deeply-nested async components, sibling async components, fragments, mixed sync+async trees, async components in non-children props, use() with promises, use() with context, rerender, error propagation, wrapper/container options, and standard render result properties. All existing tests continue to pass. TypeScript compiles clean.

A demo project using renderAsync with a Next.js App Router app and Vitest is available at aurorascharff/testing-rscs.

Resources:

• #1209 — Support for React Server Components
• Testing async React RSC components — How To Test Frontend
• Running Tests with RTL and Vitest on Async and Internationalized RSCs in Next.js App Router — Aurora Scharff

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 707a6a9:

Sandbox	Source
react-testing-library-examples	Configuration