RSC Test Helper

Common errors

• Objects are not valid as a React child (found: [object Promise]). If you meant to render a collection of children, use an array instead.

  cause React test renderers (e.g., `@testing-library/react` or `react-test-renderer`) do not natively expect async function components (like React Server Components) to return a Promise directly. When an async component is included in JSX, its return value is a Promise, which React's reconciliation process cannot render as a valid child.
  fix Apply the `patch` function from `rsc-test-helper` to your root component before rendering. For example: `const Component = await patch(<YourRootComponent />); render(<Component />);`. This transforms the async component tree into a synchronous one by resolving all promises.

Warnings

• gotcha The `patch` function, by its nature of awaiting all promises, prevents the direct testing of `<Suspense>` fallback states for the patched async components. It resolves the full component tree, bypassing intermediate loading states.
  Fix: For testing fallback states, alternative strategies (e.g., mocking the async component to return a pending promise, or using a different testing approach that doesn't resolve promises) would be necessary, but are outside the scope of this helper.
• gotcha This package is explicitly described as an 'early-stage development' and 'super dirty helper' (v0.1.4), indicating potential instability, unhandled edge cases, and that future updates, especially leading to a 1.0 release, may introduce breaking changes or significant refactors.
  Fix: Users should exercise caution and thoroughly test their applications when updating, and ideally, pin to exact versions or ranges only after careful consideration in production environments.
• gotcha The helper processes React elements in a client-side (e.g., JSDOM) testing environment. Server-side-only code, such as direct database access or other Node.js-specific APIs used within actual React Server Components, will not function correctly and may throw errors. The helper focuses on the React element transformation, not full server environment simulation.
  Fix: Components containing server-side logic might need to be mocked or abstracted for unit tests using this helper, or a Node.js-based test environment might be required for true integration testing of server-side code.

Install

• npm install rsc-test-helper npm
• yarn add rsc-test-helper yarn
• pnpm add rsc-test-helper pnpm

Imports

• patch
  wrong:

  const { patch } = require('rsc-test-helper');

  correct:

  import { patch } from 'rsc-test-helper';

  The library is primarily distributed as an ESM module, requiring `import` syntax. Although TypeScript types are shipped, direct CommonJS `require` might lead to issues depending on the project's build configuration.

Quickstart

This quickstart demonstrates how to use `rsc-test-helper`'s `patch` function to enable unit testing of a React component tree that includes an asynchronous React Server Component (RSC) within a standard testing environment like `@testing-library/react`. It shows how to resolve the common 'Objects are not valid as a React child' error by awaiting and transforming the component before rendering.

import React from "react";
import { render, screen } from "@testing-library/react";
import { patch } from "rsc-test-helper";

// Mocking internal components for a self-contained, runnable example.
// In a real application, these would be imported from their respective files.
const RoomChatParticipants = async () => {
  // Simulate an async operation, like data fetching in a Server Component
  await new Promise(resolve => setTimeout(resolve, 100)); 
  return <div data-testid="chat-participants">Participants List (from RSC)</div>;
};

const RoomChatBox = ({ subheading }: { subheading: string }) => (
  <div data-testid="chat-box">Chat Box: {subheading}</div>
);

const Skeleton = () => <div data-testid="skeleton">Loading participants...</div>;

// This component uses an async RSC (RoomChatParticipants)
const RoomPage = () => {
  return (
    <div>
      <section>
        <RoomChatBox subheading={"Welcome"} />
        <React.Suspense fallback={<Skeleton />}>
          {/* @ts-expect-error Server Component: This is a known Next.js/React pattern when using async RSCs directly in JSX */}
          <RoomChatParticipants />
        </React.Suspense>
      </section>
    </div>
  );
};

describe("Room Page with Async RSCs", () => {
  it("renders chat box and participants after patching async components", async () => {
    // Without 'patch', render(<RoomPage />) would throw an error
    // 'Objects are not valid as a React child (found: [object Promise])'.

    // 'patch' transforms the async component tree to be synchronously renderable.
    const ComponentToRender = await patch(<RoomPage />);
    render(<ComponentToRender />);

    // Verify synchronous client components are rendered
    const chatBox = screen.getByTestId("chat-box");
    expect(chatBox).toBeInTheDocument();
    expect(chatBox).toHaveTextContent("Welcome");

    // Verify the async RSC content is rendered after patching
    const participants = screen.getByTestId("chat-participants");
    expect(participants).toBeInTheDocument();
    expect(participants).toHaveTextContent("Participants List (from RSC)");

    // The skeleton fallback for Suspense is bypassed by 'patch' because promises are awaited.
    expect(screen.queryByTestId("skeleton")).not.toBeInTheDocument();
  });
});