refactor: tweaks (#32)

Author: mdjastrzebski

.github/workflows/ci.yaml

@@ -32,7 +32,6 @@ jobs:
         run: bun run test:ci
 
       - name: Upload coverage to Codecov
-        if: matrix.react-version == '19.0.0'
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -23,9 +23,11 @@ npm install -D universal-test-renderer
 import { act } from "react";
 import { createRoot } from "universal-test-renderer";
 
-test("example", () => {
+test("renders a component", async () => {
   const renderer = createRoot();
-  act(() => {
+
+  // Use `act` in async mode to allow resolving all scheduled React updates
+  await act(async () => {
     renderer.render(<div>Hello!</div>);
   });
 
@@ -39,8 +41,149 @@ test("example", () => {
 });
 ```
 
+## API Reference
+
+### `createRoot(options?)`
+
+Creates a new test renderer instance.
+
+```tsx
+const renderer = createRoot(options);
+```
+
+Returns a `Root` object with:
+
+- `render(element)` - Render a React element. Must be called within `act()`.
+- `unmount()` - Unmount and clean up. Must be called within `act()`.
+- `container` - A wrapper `HostElement` that contains the rendered element(s). Use this to query and inspect the rendered tree.
+
+### `RootOptions`
+
+| Option               | Type                         | Description                                                       |
+| -------------------- | ---------------------------- | ----------------------------------------------------------------- |
+| `textComponents`     | `string[]`                   | Element types that can contain text (for React Native simulation) |
+| `createNodeMock`     | `(element) => object`        | Create mock objects for refs                                      |
+| `identifierPrefix`   | `string`                     | Prefix for `useId()` generated IDs                                |
+| `isStrictMode`       | `boolean`                    | Enable React Strict Mode                                          |
+| `onCaughtError`      | `(error, errorInfo) => void` | Called when Error Boundary catches an error                       |
+| `onUncaughtError`    | `(error, errorInfo) => void` | Called for uncaught errors                                        |
+| `onRecoverableError` | `(error, errorInfo) => void` | Called when React recovers from errors                            |
+
+### `HostElement`
+
+The rendered element wrapper with a DOM-like API:
+
+| Property/Method                 | Description                              |
+| ------------------------------- | ---------------------------------------- |
+| `type`                          | Element type (e.g., `"div"`, `"span"`)   |
+| `props`                         | Element props object                     |
+| `children`                      | Array of child elements and text strings |
+| `parent`                        | Parent element or `null`                 |
+| `toJSON()`                      | Convert to JSON for snapshots            |
+| `queryAll(predicate, options?)` | Find all matching descendant elements    |
+
+## Querying Elements
+
+Use `queryAll()` to find elements in the rendered tree:
+
+```tsx
+const renderer = createRoot();
+await act(async () => {
+  renderer.render(
+    <div>
+      <button data-testid="btn-1">First</button>
+      <button data-testid="btn-2">Second</button>
+    </div>,
+  );
+});
+
+// Find all buttons
+const buttons = renderer.container.queryAll((el) => el.type === "button");
+expect(buttons).toHaveLength(2);
+
+// Find by props
+const btn1 = renderer.container.queryAll((el) => el.props["data-testid"] === "btn-1");
+expect(btn1[0].children).toContain("First");
+```
+
+### Query Options
+
+```tsx
+queryAll(predicate, {
+  includeSelf: false, // Include the element itself in results
+  matchDeepestOnly: false, // Only return deepest matches (exclude ancestors)
+});
+```
+
+## React Native Simulation
+
+Use `textComponents` to simulate React Native's text rendering rules:
+
+```tsx
+import { createElement } from "react";
+
+const renderer = createRoot({
+  textComponents: ["Text", "RCTText"],
+});
+
+// This works - text inside Text component
+await act(async () => {
+  renderer.render(createElement("Text", null, "Hello!"));
+});
+
+// This throws - text outside Text component
+await act(async () => {
+  renderer.render(<View>Hello!</View>); // Error!
+});
+```
+
+## Mocking Refs
+
+Use `createNodeMock` to provide mock objects for refs:
+
+```tsx
+const renderer = createRoot({
+  createNodeMock: (element) => {
+    if (element.type === "input") {
+      return {
+        focus: jest.fn(),
+        value: "",
+      };
+    }
+    return {};
+  },
+});
+
+await act(async () => {
+  renderer.render(<input ref={inputRef} />);
+});
+
+// inputRef.current is now the mock object
+inputRef.current.focus();
+```
+
+## Error Handling
+
+Handle React errors with custom callbacks:
+
+```tsx
+const renderer = createRoot({
+  onCaughtError: (error, errorInfo) => {
+    // Called when an Error Boundary catches an error
+    console.log("Caught:", error.message);
+    console.log("Component stack:", errorInfo.componentStack);
+  },
+  onUncaughtError: (error, errorInfo) => {
+    // Called for uncaught render errors
+  },
+});
+```
+
 ## Key Differences from React Test Renderer
 
 - Works at host component level only (no composite components)
-- More flexible reconciler configuration options
-- Uses `act` from the React package directly
+- Expost all reconciler configuration options
+
+## License
+
+MIT

jest.config.js

@@ -3,4 +3,5 @@ export default {
   testEnvironment: "node",
   testMatch: ["**/__tests__/**/*.ts?(x)", "**/?(*.)+(spec|test).ts?(x)"],
   moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  coveragePathIgnorePatterns: ["/node_modules/", "/test-utils/"],
 };

package.json

@@ -1,9 +1,16 @@
 {
   "name": "universal-test-renderer",
   "version": "0.10.1",
-  "description": "",
-  "keywords": [],
-  "author": "",
+  "description": "A lightweight, JavaScript-only replacement for the deprecated React Test Renderer.",
+  "keywords": [
+    "react",
+    "react-test-renderer",
+    "testing",
+    "test-renderer",
+    "react-19",
+    "jest"
+  ],
+  "author": "Maciej Jastrzebski <mdjastrzebski@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",

src/__tests__/create-node-mock.test.tsx

@@ -5,7 +5,6 @@ import { createRoot } from "../renderer";
 import { renderWithAct } from "../test-utils/render";
 
 beforeEach(() => {
-  // @ts-expect-error global is not typed
   global.IS_REACT_ACT_ENVIRONMENT = true;
 });
 

src/__tests__/host-element.test.tsx

@@ -1,12 +1,11 @@
 import { beforeEach, expect, jest, test } from "@jest/globals";
 
 import type { HostElement } from "../host-element";
-import { ReactWorkTag } from "../react-constants";
 import { createRoot } from "../renderer";
+import { ReactWorkTag } from "../test-utils/react-constants";
 import { getRootElement, renderWithAct } from "../test-utils/render";
 
 beforeEach(() => {
-  // @ts-expect-error global is not typed
   global.IS_REACT_ACT_ENVIRONMENT = true;
 });
 

src/__tests__/renderer.test.tsx

@@ -5,7 +5,6 @@ import { createRoot } from "../renderer";
 import { renderWithAct } from "../test-utils/render";
 
 beforeEach(() => {
-  // @ts-expect-error global is not typed
   global.IS_REACT_ACT_ENVIRONMENT = true;
 });
 

src/__tests__/root-options.test.tsx

@@ -0,0 +1,99 @@
+import { beforeEach, expect, jest, test } from "@jest/globals";
+import { Component, useEffect, useId } from "react";
+
+import { createRoot } from "../renderer";
+import { renderWithAct } from "../test-utils/render";
+
+beforeEach(() => {
+  global.IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+test("isStrictMode option enables strict mode", async () => {
+  let renderCount = 0;
+  let effectCount = 0;
+
+  function Counter() {
+    renderCount++;
+    useEffect(() => {
+      effectCount++;
+    }, []);
+    return <div>Count: {renderCount}</div>;
+  }
+
+  const renderer = createRoot({ isStrictMode: true });
+  await renderWithAct(renderer, <Counter />);
+
+  // In strict mode, components render twice and effects run twice
+  expect(renderCount).toBe(2);
+  expect(effectCount).toBe(2);
+});
+
+test("identifierPrefix option prefixes useId values", async () => {
+  let capturedId: string | undefined;
+
+  function ComponentWithId() {
+    capturedId = useId();
+    return <div id={capturedId}>Content</div>;
+  }
+
+  const renderer = createRoot({ identifierPrefix: "test-prefix-" });
+  await renderWithAct(renderer, <ComponentWithId />);
+
+  expect(capturedId).toBeDefined();
+  expect(capturedId).toContain("test-prefix-");
+});
+
+interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+    return this.props.children;
+  }
+}
+
+test("onCaughtError is called when error is caught by Error Boundary", async () => {
+  const onCaughtError = jest.fn();
+
+  function ThrowingComponent(): React.ReactNode {
+    throw new Error("Test caught error");
+  }
+
+  const renderer = createRoot({ onCaughtError });
+  await renderWithAct(
+    renderer,
+    <ErrorBoundary fallback={<div>Error caught</div>}>
+      <ThrowingComponent />
+    </ErrorBoundary>,
+  );
+
+  expect(renderer.container).toMatchInlineSnapshot(`
+    <>
+      <div>
+        Error caught
+      </div>
+    </>
+  `);
+
+  expect(onCaughtError).toHaveBeenCalledTimes(1);
+  expect(onCaughtError.mock.calls[0]?.[0]).toBeInstanceOf(Error);
+  expect((onCaughtError.mock.calls[0]?.[0] as Error).message).toBe("Test caught error");
+});

src/__tests__/suspense.test.tsx

@@ -5,7 +5,6 @@ import { createRoot } from "../renderer";
 import { act, renderWithAct } from "../test-utils/render";
 
 beforeEach(() => {
-  // @ts-expect-error global is not typed
   global.IS_REACT_ACT_ENVIRONMENT = true;
 });
 

src/__tests__/unmount.test.tsx

@@ -4,7 +4,6 @@ import { createRoot } from "../renderer";
 import { renderWithAct, unmountWithAct } from "../test-utils/render";
 
 beforeEach(() => {
-  // @ts-expect-error global is not typed
   global.IS_REACT_ACT_ENVIRONMENT = true;
 });
 
@@ -18,10 +17,7 @@ test("unmount clears the rendered content", async () => {
   await unmountWithAct(renderer);
   expect(containerElement.children.length).toBe(0);
 
-  expect(() => {
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    renderer.container;
-  }).toThrow("Can't access .container on unmounted test renderer");
+  expect(() => renderer.container).toThrow("Cannot access .container on unmounted test renderer");
 });
 
 test("unmount can be called multiple times safely", async () => {
@@ -36,21 +32,15 @@ test("unmount can be called multiple times safely", async () => {
   await unmountWithAct(renderer);
   expect(containerElement.children.length).toBe(0);
 
-  expect(() => {
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    renderer.container;
-  }).toThrow("Can't access .container on unmounted test renderer");
+  expect(() => renderer.container).toThrow("Cannot access .container on unmounted test renderer");
 });
 
 test("unmount when nothing is rendered", async () => {
   const renderer = createRoot();
 
   await expect(() => unmountWithAct(renderer)).resolves.not.toThrow();
 
-  expect(() => {
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    renderer.container;
-  }).toThrow("Can't access .container on unmounted test renderer");
+  expect(() => renderer.container).toThrow("Cannot access .container on unmounted test renderer");
 });
 
 test("cannot render after unmount", async () => {