Test Renderer for React

A lightweight, JS-only building block for creating Testing Library-style libraries.

This library is used by React Native Testing Library but is written generically to support different React variants and custom renderers.

This library also serves as a replacement for the deprecated React Test Renderer. It is built using React Reconciler to provide a custom renderer that operates on host elements by default, with proper escape hatches when needed. Most React Reconciler options are exposed for maximum flexibility.

Installation

yarn add -D test-renderer

Getting Started

import { createRoot } from "test-renderer";
import { act } from "react";

test("renders a component", async () => {
  const renderer = createRoot();

  // Use `act` in async mode to allow resolving all scheduled React updates
  await act(async () => {
    renderer.render(<div>Hello!</div>);
  });

  expect(renderer.container).toMatchInlineSnapshot(`
    <>
      <div>
        Hello!
      </div>
    </>
  `);
});

API Reference

createRoot(options?)

Creates a new test renderer root instance.

Parameters:

• options (optional): Configuration options for the renderer. See RootOptions below.

Returns: A Root object with the following properties:

• render(element: ReactElement): Renders a React element into the root. Must be called within act().
• unmount(): Unmounts the root and cleans up. Must be called within act().
• container: A HostElement wrapper that contains the rendered element(s). Use this to query and inspect the rendered tree.

Example:

const renderer = createRoot();
await act(async () => {
  renderer.render(<div>Hello!</div>);
});

RootOptions

Configuration options for the test renderer. Many of these options correspond to React Reconciler configuration options. For detailed information about reconciler-specific options, refer to the React Reconciler source code.

| Option | Type | Description | | -------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | textComponentTypes | string[] | Types of host components that are allowed to contain text nodes. Trying to render text outside of these components will throw an error. Useful for simulating React Native's text rendering rules. | | publicTextComponentTypes | string[] | Host component types to display to users in error messages when they try to render text outside of textComponentTypes. Defaults to textComponentTypes if not provided. | | createNodeMock | (element: ReactElement) => object | Function to create mock objects for refs. Called once per element that has a ref. Defaults to returning an empty object. | | identifierPrefix | string | A string prefix React uses for IDs generated by useId(). Useful to avoid conflicts when using multiple roots. | | isStrictMode | boolean | Enable React Strict Mode. When enabled, components render twice and effects run twice in development. | | onCaughtError | (error: unknown, errorInfo: { componentStack?: string }) => void | Callback called when React catches an error in an Error Boundary. Called with the error caught by the Error Boundary and an errorInfo object containing the component stack. | | onUncaughtError | (error: unknown, errorInfo: { componentStack?: string }) => void | Callback called when an error is thrown and not caught by an Error Boundary. Called with the error that was thrown and an errorInfo object containing the component stack. | | onRecoverableError | (error: unknown, errorInfo: { componentStack?: string }) => void | Callback called when React automatically recovers from errors. Called with an error React throws and an errorInfo object containing the component stack. Some recoverable errors may include the original error cause as error.cause. |

HostElement

A wrapper around rendered host elements that provides a DOM-like API for querying and inspecting the rendered tree.

Properties:

• type: string: The element type (e.g., "View", "div"). Returns an empty string for the container element.
• props: HostElementProps: The element's props object.
• children: HostNode[]: Array of child nodes (elements and text strings). Hidden children are excluded.
• parent: HostElement | null: The parent element, or null if this is the root container.
• unstable_fiber: Fiber | null: Access to the underlying React Fiber node. Warning: This is an unstable API that exposes internal React Reconciler structures which may change without warning in future React versions. Use with caution and only when absolutely necessary.

Methods:

• toJSON(): JsonElement | null: Converts this element to a JSON representation suitable for snapshots. Returns null if the element is hidden.
• queryAll(predicate: (element: HostElement) => boolean, options?: QueryOptions): HostElement[]: Finds all descendant elements matching the predicate. See Query Options below.

Example:

const renderer = createRoot();
await act(async () => {
  renderer.render(<div className="container">Hello</div>);
});

const root = renderer.container.children[0] as HostElement;
expect(root.type).toBe("div");
expect(root.props.className).toBe("container");
expect(root.children).toContain("Hello");

QueryOptions

Options for configuring element queries.

| Option | Type | Default | Description | | ------------------ | --------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | includeSelf | boolean | false | Include the element itself in the results if it matches the predicate. | | matchDeepestOnly | boolean | false | Exclude any ancestors of deepest matched elements even if they match the predicate. Only return the deepest matches. |

Example:

// Find all divs, including nested ones
const allDivs = container.queryAll((el) => el.type === "div");

// Find only the deepest divs (exclude parent divs if they contain matching children)
const deepestDivs = container.queryAll((el) => el.type === "div", { matchDeepestOnly: true });

// Include the container itself if it matches
const includingSelf = container.queryAll((el) => el.type === "div", { includeSelf: true });

Migration from React Test Renderer

This library serves as a replacement for the deprecated React Test Renderer. The main differences are:

• Host element focus: This library operates on host components by default, while React Test Renderer worked with a mix of host and composite components. You can access the underlying fiber via unstable_fiber if needed.
• Built on React Reconciler: This library is built using React Reconciler, providing a custom renderer implementation.
• Exposed reconciler options: Most React Reconciler configuration options are exposed through RootOptions for maximum flexibility.

For most use cases, the migration is straightforward:

// Before (React Test Renderer)
import TestRenderer from "react-test-renderer";
const tree = TestRenderer.create(<MyComponent />);

// After (test-renderer)
import { createRoot } from "test-renderer";
const root = createRoot();
await act(async () => {
  root.render(<MyComponent />);
});
const tree = root.container;

Supported React Features

This library supports all modern React features including:

• Concurrent rendering
• Error boundaries
• Suspense boundaries

License

MIT