React Testing

React tests use @pai/react-test-utils. For contract-bound renderer and client harness tests, create one typed helper from your React binding:

import { createReactTestUtils } from "@pai/react-test-utils";
import { Pai, SupportAI } from "./pai";

const t = createReactTestUtils({ Pai, AI: SupportAI });

The examples in this section use React Testing Library and user-event because they are common React testing tools. PAI does not require either one; the React test utilities provide typed fixtures and mock client providers that can be used with your app's existing React test renderer.

There are three normal frontend layers. Pick the smallest layer that includes the boundary you need to prove.

The Boundary

Renderer tests start with typed props. They do not create a thread.

const compareProposals = t.toolProps("compareProposals");
const tool = compareProposals.outputAvailable({ input, output });

render(<CompareProposalsRenderer tool={tool} />);

Client harness tests mount the real React integration, but there is no runtime behind it. The test scripts the same public thread state a real client would receive from a server. PAI provides the provider harness; your test suite still uses its normal React render helper.

await using h = t.createClientHarness({ threadId: "thread-1" });

await h.driver.responses.queue((r) =>
  r.assistant([r.text("Searching agencies complete.")]),
);

render(<ChatSurface />, { wrapper: h.Provider });

Choosing A Layer

Use backend agent/runtime tests to prove how runtime state is produced. Use client harness tests to prove React behavior against that public state shape.

What Not To Do

• Do not import the real server agent for a renderer unit test.
• Do not mock React hooks directly when the client harness can mount real providers.
• Do not import the real server agent into frontend tests just to get a typed contract. Prefer generated contracts.
• Do not use fireEvent for normal user interactions; prefer userEvent.setup() and await user.click(...).

Next

• Renderer Tests: pure tool renderer and visual state tests.
• Client Tool Tests: execute and render one client-defined tool without app providers.
• Client Harness Tests: React providers, hooks, scripted client state, thread lists, client tools, and timing.
• React Testing API Reference: public @pai/react-test-utils helper summary.