refactor: rename to TestInstance (#43)

Author: mdjastrzebski

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-**Test Renderer for React** is a lightweight, pure JavaScript testing library for React 19. It replaces the deprecated `react-test-renderer`. Built with `react-reconciler`, it outputs to a lightweight, traversable object structure (`HostElement`) for snapshot testing and asserting component output without a browser environment (DOM) or native dependencies.
+**Test Renderer for React** is a lightweight, pure JavaScript testing library for React 19. It replaces the deprecated `react-test-renderer`. Built with `react-reconciler`, it outputs to a lightweight, traversable object structure (`TestInstance`) for snapshot testing and asserting component output without a browser environment (DOM) or native dependencies.
 
 ### Key Features
 
@@ -16,8 +16,8 @@
 - **`src/index.ts`**: The public entry point that exports `createRoot` from `renderer.ts`.
 - **`src/renderer.ts`**: Contains the main implementation. Exports `createRoot` which initializes the custom React reconciler.
 - **`src/reconciler.ts`**: Implements the `react-reconciler` host config, translating React updates into operations on the internal tree.
-- **`src/host-element.ts`**: Defines `HostElement`, a wrapper around the internal fiber nodes with a DOM-like API (e.g., `children`, `props`, `parent`).
-- **`src/render-to-json.ts`**: Handles the serialization of `HostElement` trees into JSON format for snapshots.
+- **`src/test-instance.ts`**: Defines `TestInstance`, a wrapper around the internal fiber nodes with a DOM-like API (e.g., `children`, `props`, `parent`).
+- **`src/render-to-json.ts`**: Handles the serialization of `TestInstance` trees into JSON format for snapshots.
 
 ## Building and Running
 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -44,6 +44,26 @@ This library supports all modern React features including:
 - Error boundaries
 - Suspense boundaries
 
+## Test Output Tree
+
+Instead of producing a DOM tree or a native view hierarchy, the renderer builds an in-memory **Test Output Tree**:
+
+- Composed of **`TestNode`s**, where each node is either:
+  - A **`TestInstance`** — represents a host element such as `div` or `View`
+  - A plain **`string`** — represents a text node
+- The root is accessible via `root.container`, a `TestInstance` whose `type` is an empty string
+- `TestInstance` nodes are traversable and queryable — see the [`TestInstance`](#testelement) API below
+
+## JSON Output Tree
+
+Calling `toJSON()` on a `TestInstance` produces a **JSON Output Tree** — a static, plain-object snapshot of the Test Output Tree at that point in time:
+
+- Composed of **`JsonNode`s**, where each node is either:
+  - A **`JsonElement`** — a plain object with `type`, `props`, and `children`
+  - A plain **`string`** — a text node
+- Contains no live references, making it safe to serialize
+- Ideal for snapshot testing
+
 ## API Reference
 
 ### `createRoot(options?)`
@@ -58,7 +78,7 @@ Creates a new test renderer root instance.
 
 - `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.
+- `container`: A `TestInstance` wrapper that contains the rendered element(s). Use this to query and inspect the rendered tree.
 
 **Example:**
 
@@ -84,22 +104,22 @@ Configuration options for the test renderer. Many of these options correspond to
 | `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`
+### `TestInstance` {#test-instance}
 
 A wrapper around rendered host elements with 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.
+- `props: Record<string, all>`: 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.
+- `parent: TestInstance | 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](#query-options) below.
+- `queryAll(predicate: (instance: TestInstance) => boolean, options?: QueryOptions): TestInstance[]`: Finds all descendant elements matching the predicate. See [Query Options](#query-options) below.
 
 **Example:**
 
@@ -109,7 +129,7 @@ await act(async () => {
   renderer.render(<div className="container">Hello</div>);
 });
 
-const root = renderer.container.children[0] as HostElement;
+const root = renderer.container.children[0] as TestInstance;
 expect(root.type).toBe("div");
 expect(root.props.className).toBe("container");
 expect(root.children).toContain("Hello");

src/__tests__/host-element.test.tsx src/__tests__/test-instance.test.tsxsrc/__tests__/host-element.test.tsx renamed to src/__tests__/test-instance.test.tsx

@@ -1,9 +1,9 @@
 import { beforeEach, expect, jest, test } from "@jest/globals";
 
-import type { HostElement } from "../host-element";
 import { createRoot } from "../renderer";
+import type { TestInstance } from "../test-instance";
 import { ReactWorkTag } from "../test-utils/react-constants";
-import { getRootElement, renderWithAct } from "../test-utils/render";
+import { getRootInstance, renderWithAct } from "../test-utils/render";
 
 beforeEach(() => {
   global.IS_REACT_ACT_ENVIRONMENT = true;
@@ -13,7 +13,7 @@ test("container is root's parent", async () => {
   const renderer = createRoot();
   await renderWithAct(renderer, <div>Hello!</div>);
 
-  const root = getRootElement(renderer);
+  const root = getRootInstance(renderer);
   expect(root).toBeTruthy();
   expect(root.parent).toBe(renderer.container);
   expect(root.parent!.parent).toBeNull();
@@ -29,9 +29,9 @@ test("basic parent/child relationships", async () => {
     </div>,
   );
 
-  const root = getRootElement(renderer);
-  const item1 = root.children[0] as HostElement;
-  const item2 = root.children[1] as HostElement;
+  const root = getRootInstance(renderer);
+  const item1 = root.children[0] as TestInstance;
+  const item2 = root.children[1] as TestInstance;
   expect(item1.props["data-testid"]).toBe("item-1");
   expect(item2.props["data-testid"]).toBe("item-2");
   expect(item1.parent).toBe(root);
@@ -42,7 +42,7 @@ test("host elements exposes fiber instance", async () => {
   const renderer = createRoot();
   await renderWithAct(renderer, <div>Hello!</div>);
 
-  const root = getRootElement(renderer);
+  const root = getRootInstance(renderer);
   const fiber = root.unstable_fiber!;
   expect(fiber.tag).toBe(ReactWorkTag.HostComponent);
   expect(fiber.return!.tag).toBe(ReactWorkTag.HostRoot);
@@ -62,7 +62,7 @@ test("can access composite parent props", async () => {
   const renderer = createRoot();
   await renderWithAct(renderer, <TestComponent className="test-class" onChange={handleChange} />);
 
-  const root = getRootElement(renderer);
+  const root = getRootInstance(renderer);
   expect(root.props).toEqual({ className: "test-class", children: "Hello!" });
 
   const fiber = root.unstable_fiber!;
@@ -136,7 +136,7 @@ test("queryAll should not return self by default", async () => {
     </body>,
   );
 
-  const elements = getRootElement(renderer).queryAll(
+  const elements = getRootInstance(renderer).queryAll(
     (element) => element.props.className === "yes",
   );
   expect(elements).toHaveLength(2);
@@ -155,7 +155,7 @@ test("queryAll should return self if 'includeSelf' is true", async () => {
     </body>,
   );
 
-  const elements = getRootElement(renderer).queryAll(
+  const elements = getRootInstance(renderer).queryAll(
     (element) => element.props.className === "yes",
     {
       includeSelf: true,

src/__tests__/unmount.test.tsx

@@ -11,11 +11,11 @@ test("unmount clears the rendered content", async () => {
   const renderer = createRoot();
   await renderWithAct(renderer, <div>Hello!</div>);
 
-  const containerElement = renderer.container;
-  expect(containerElement.children.length).toBe(1);
+  const container = renderer.container;
+  expect(container.children.length).toBe(1);
 
   await unmountWithAct(renderer);
-  expect(containerElement.children.length).toBe(0);
+  expect(container.children.length).toBe(0);
 
   expect(() => renderer.container).toThrow("Cannot access .container on unmounted test renderer");
 });
@@ -24,13 +24,13 @@ test("unmount can be called multiple times safely", async () => {
   const renderer = createRoot();
   await renderWithAct(renderer, <div>Hello!</div>);
 
-  const containerElement = renderer.container;
-  expect(containerElement.children.length).toBe(1);
+  const container = renderer.container;
+  expect(container.children.length).toBe(1);
 
   await unmountWithAct(renderer);
   await unmountWithAct(renderer);
   await unmountWithAct(renderer);
-  expect(containerElement.children.length).toBe(0);
+  expect(container.children.length).toBe(0);
 
   expect(() => renderer.container).toThrow("Cannot access .container on unmounted test renderer");
 });

src/index.ts

@@ -1,13 +1,15 @@
 export { createRoot } from "./renderer";
 
 export type { Root, RootOptions } from "./renderer";
-export type { HostElement, HostElementProps, HostNode } from "./host-element";
-export type { JsonElement, JsonNode } from "./render-to-json";
+
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export type { TestInstance, TestNode, HostElement } from "./test-instance";
+export type { JsonElement, JsonNode } from "./to-json";
 export type { QueryOptions } from "./query-all";
 
 /**
  * React Fiber type from react-reconciler. Exported for advanced use cases only.
  * This type represents internal React structures that may change without warning.
- * Prefer using the stable HostElement API instead.
+ * Prefer using the stable TestInstance API instead.
  */
 export type { Fiber } from "react-reconciler";

src/query-all.ts

@@ -1,38 +1,38 @@
-import type { HostElement } from "./host-element";
+import type { TestInstance } from "./test-instance";
 
 /**
  * Options for querying elements in the rendered tree.
  */
 export interface QueryOptions {
-  /** Include the element itself in the results if it matches the predicate. Defaults to false. */
+  /** Include the instance itself in the results if it matches the predicate. Defaults to false. */
   includeSelf?: boolean;
 
-  /** Exclude any ancestors of deepest matched elements even if they match the predicate. Defaults to false. */
+  /** Exclude any ancestors of deepest matched instances even if they match the predicate. Defaults to false. */
   matchDeepestOnly?: boolean;
 }
 
 /**
  * Find all descendant elements matching the predicate.
  *
- * @param element - Root element to search from.
+ * @param instance - Root TestInstance to search from.
  * @param predicate - Function that returns true for matching elements.
  * @param options - Optional query configuration.
  * @returns Array of matching elements in tree order.
  */
 export function queryAll(
-  element: HostElement,
-  predicate: (element: HostElement) => boolean,
+  instance: TestInstance,
+  predicate: (instance: TestInstance) => boolean,
   options?: QueryOptions,
-): HostElement[] {
+): TestInstance[] {
   const includeSelf = options?.includeSelf ?? false;
   const matchDeepestOnly = options?.matchDeepestOnly ?? false;
 
-  const results: HostElement[] = [];
+  const results: TestInstance[] = [];
 
   // Match descendants first but do not add them to results yet.
-  const matchingDescendants: HostElement[] = [];
+  const matchingDescendants: TestInstance[] = [];
 
-  element.children.forEach((child) => {
+  instance.children.forEach((child) => {
     if (typeof child === "string") {
       return;
     }
@@ -44,9 +44,9 @@ export function queryAll(
     includeSelf &&
     // When matchDeepestOnly = true: add current element only if no descendants match
     (matchingDescendants.length === 0 || !matchDeepestOnly) &&
-    predicate(element)
+    predicate(instance)
   ) {
-    results.push(element);
+    results.push(instance);
   }
 
   // Add matching descendants after element to preserve original tree walk order.

src/renderer.ts

@@ -2,10 +2,10 @@ import type { ReactElement } from "react";
 import { ConcurrentRoot } from "react-reconciler/constants";
 
 import { Tag } from "./constants";
-import { HostElement } from "./host-element";
 import { measureEnd, measureStart } from "./performance";
 import type { Container } from "./reconciler";
 import { TestReconciler } from "./reconciler";
+import { TestInstance } from "./test-instance";
 
 // Refs:
 // https://github.com/facebook/react/blob/main/packages/react-test-renderer/src/ReactFiberConfigTestHost.js
@@ -73,7 +73,7 @@ export type Root = {
   /** Unmount the root and clean up. Must be called within act(). */
   unmount: () => void;
   /** The root container element. */
-  container: HostElement;
+  container: TestInstance;
 };
 
 /**
@@ -151,12 +151,12 @@ export function createRoot(options?: RootOptions): Root {
   return {
     render,
     unmount,
-    get container(): HostElement {
+    get container(): TestInstance {
       if (container == null) {
         throw new Error("Cannot access .container on unmounted test renderer");
       }
 
-      return HostElement.fromInstance(container);
+      return TestInstance.fromInstance(container);
     },
   };
 }