#Testing

// rstest.route-unit.config.ts
import { defineConfig } from '@rstest/core';
import { agentBundleRstest } from 'agent-bundle/rstest';

export default defineConfig(await agentBundleRstest());

import { 
const expectDocument: (subject: DocumentSubject) => DocumentAssertionsexpectDocument, 
const renderRoute: (target: RenderRouteTarget, options?: RenderRouteOptions | undefined) => Promise<RenderedRoute>
Renders one route through the real Agent renderer and returns its final
Agent Document. The route component executes inside a real request scope,
its output is encoded as React Flight, and the runtime's own final-only
dispatcher decodes it — the harness owns no second rendering path.
This is the route-unit proof level: no transport is opened, no browser
surface is compiled, and no host artifact is built.renderRoute } from 'agent-bundle/test';

export const 
const summarizes: () => Promise<void>summarizes = async (): 
interface Promise<T>
Represents the completion of an asynchronous operationPromise<void> => {
  const { 
const document: AgentDocument
The final Agent Document the real renderer produced.document } = await 
function renderRoute(target: RenderRouteTarget, options?: RenderRouteOptions | undefined): Promise<RenderedRoute>
Renders one route through the real Agent renderer and returns its final
Agent Document. The route component executes inside a real request scope,
its output is encoded as React Flight, and the runtime's own final-only
dispatcher decodes it — the harness owns no second rendering path.
This is the route-unit proof level: no transport is opened, no browser
surface is compiled, and no host artifact is built.renderRoute('tool:library/summarize', {
    
RenderRouteOptionsBase.input?: unknown
The route's input: tool input, event payload, or script input.input: { 
title: stringtitle: 'Dune' },
  });

  
function expectDocument(subject: DocumentSubject): DocumentAssertionsexpectDocument(
const document: AgentDocument
The final Agent Document the real renderer produced.document)
    .
DocumentAssertions.toHaveStatus: (status: AgentDocumentStatus) => DocumentAssertionstoHaveStatus('success')
    .
DocumentAssertions.toContainMarkdown: (text: string) => DocumentAssertions
Asserts a Markdown node contains text.toContainMarkdown('Dune')
    .
DocumentAssertions.toHaveValue: (value: unknown) => DocumentAssertions
Asserts the document's structured value equals value (JSON structural
equality). undefined asserts the document emitted no value at all, which
null does not satisfy.toHaveValue({ 
chapters: numberchapters: 24 });
};

import { 
const cliJson: (invocation: CliInvocation) => unknown
The parsed canonical JSON line a successful command wrote to stdout.cliJson, 
const cliNdjson: (invocation: CliInvocation) => readonly CliRenderedEvent[]
The ordered render events a successful --ndjson invocation wrote to stdout.cliNdjson, 
const invokeCli: (argv: readonly string[], options?: InvokeCliOptions | undefined) => Promise<CliInvocation>
Dispatches one argv vector through the routed CLI shell in this process and
returns its exit code, streams, and validated result.
This is the cli-dispatch proof level. Nothing is spawned.invokeCli, 
const invokeMcpTool: (tool: string, options?: McpInvocationOptions | undefined) => Promise<McpToolInvocation>
Calls one compiled tool through the real protocol and returns the projected
result. mcp-in-memory level: protocol contract proof, not process proof.invokeMcpTool } from 'agent-bundle/test';

export const 
const proofs: () => Promise<Record<string, unknown>>proofs = async (): 
interface Promise<T>
Represents the completion of an asynchronous operationPromise<
type Record<K extends keyof any, T> = { [P in K]: T; }
Construct a type with a set of properties K of type TRecord<string, unknown>> => {
  // mcp-in-memory: the generated server projects the document to protocol content.
  const 
const call: McpToolInvocationcall = await 
function invokeMcpTool(tool: string, options?: McpInvocationOptions | undefined): Promise<McpToolInvocation>
Calls one compiled tool through the real protocol and returns the projected
result. mcp-in-memory level: protocol contract proof, not process proof.invokeMcpTool('summarize', { 
input?: unknowninput: { 
title: stringtitle: 'Dune' } });

  // cli-dispatch, plain .ts route: resolve argv, execute, and map the exit code.
  const 
const run: CliInvocationrun = await 
function invokeCli(argv: readonly string[], options?: InvokeCliOptions | undefined): Promise<CliInvocation>
Dispatches one argv vector through the routed CLI shell in this process and
returns its exit code, streams, and validated result.
This is the cli-dispatch proof level. Nothing is spawned.invokeCli(['library', 'audit', './books', '--max-files', '8']);

  // cli-dispatch, rendered .tsx route: exercise the shell's rendered output modes.
  const 
const rendered: CliInvocationrendered = await 
function invokeCli(argv: readonly string[], options?: InvokeCliOptions | undefined): Promise<CliInvocation>
Dispatches one argv vector through the routed CLI shell in this process and
returns its exit code, streams, and validated result.
This is the cli-dispatch proof level. Nothing is spawned.invokeCli(['library', 'report', './books', '--ndjson']);
  const 
const events: readonly CliRenderedEvent[]events = 
function cliNdjson(invocation: CliInvocation): readonly CliRenderedEvent[]
The ordered render events a successful --ndjson invocation wrote to stdout.cliNdjson(
const rendered: CliInvocationrendered);

  // An explicit TTY proves the in-place progress path rather than the piped one.
  const 
const tty: CliInvocationtty = await 
function invokeCli(argv: readonly string[], options?: InvokeCliOptions | undefined): Promise<CliInvocation>
Dispatches one argv vector through the routed CLI shell in this process and
returns its exit code, streams, and validated result.
This is the cli-dispatch proof level. Nothing is spawned.invokeCli(['library', 'report', './books'], { 
InvokeCliOptionsBase.tty?: boolean | undefined
Selects interactive rendered output explicitly. Generated binaries use
process.stdout.isTTY; the in-process harness defaults to piped output.tty: true });

  return {
    
exitCode: numberexitCode: 
const run: CliInvocationrun.
CliInvocation.exitCode: number
The process exit code the routed shell mapped: 0 success (or the result's
exitCode under config.exitCode: 'result'), 1 execution failure,
2 usage or input-validation failure.exitCode,
    
finalEvent: "shell" | "progress" | "replace" | "error" | "complete" | undefinedfinalEvent: 
const events: readonly CliRenderedEvent[]events.
ReadonlyArray<CliRenderedEvent>.at(index: number): CliRenderedEvent | undefined
Returns the item located at the specified index.
@paramindex  The zero-based index of the desired code unit. A negative index will count back from the last item.at(-1)?.
type: "shell" | "progress" | "replace" | "error" | "complete" | undefinedtype,
    
inPlaceProgress: booleaninPlaceProgress: 
const tty: CliInvocationtty.
CliInvocation.stdout: string
Everything the shell wrote to stdout, including rendered Markdown, TTY, JSON, or NDJSON output.stdout.
String.includes(searchString: string, position?: number): boolean
Returns true if searchString appears as a substring of the result of converting this
object to a String, at one or more positions that are
greater than or equal to position; otherwise, returns false.
@paramsearchString  search string@paramposition  If position is undefined, 0 is assumed, so as to search all of the String.includes('\r\u001B[2K'),
    
scanned: unknownscanned: 
function cliJson(invocation: CliInvocation): unknown
The parsed canonical JSON line a successful command wrote to stdout.cliJson(
const run: CliInvocationrun),
    
structured: unknownstructured: 
const call: McpToolInvocationcall.
McpToolInvocation.structuredContent?: unknownstructuredContent,
  };
};

import { 
const runContractMatrix: (options: ContractMatrixOptions) => Promise<ContractMatrixReport>
Runs the contract matrix against one compiled MCP server at the
mcp-in-memory proof level. Returns a per-route report; throws one
aggregated AgentTestError with code contract-violation when any check
failed (never first-failure-only).runContractMatrix } from 'agent-bundle/test';

export const 
const matrix: () => Promise<void>matrix = async (): 
interface Promise<T>
Represents the completion of an asynchronous operationPromise<void> => {
  await 
function runContractMatrix(options: ContractMatrixOptions): Promise<ContractMatrixReport>
Runs the contract matrix against one compiled MCP server at the
mcp-in-memory proof level. Returns a per-route report; throws one
aggregated AgentTestError with code contract-violation when any check
failed (never first-failure-only).runContractMatrix({
    
ContractMatrixOptions.fixtures: Readonly<Record<string, ContractRouteFixture>>
Route id -> fixture. Every compiled tool, prompt, and resource route on
the server must be covered. App routes are not registered at
mcp-in-memory; entries for them are accepted and ignored.fixtures: {
      'tool:library/summarize': {
        
ContractRouteFixture.input?: unknown
Valid input for the sweep invocation (tools/prompts; resources need none).input: { 
title: stringtitle: 'Dune' },
        
ContractRouteFixture.previousResults?: readonly unknown[] | undefined
Serialized payloads captured from previous server versions; each must parse
under the CURRENT resultSchema (previous-server + current-client skew).previousResults: [{ 
chapters: numberchapters: 24 }],
        
ContractRouteFixture.resultCompat?: ResultCompatPolicy | undefined
Declared serialized-result compatibility policy. REQUIRED for tool routes.resultCompat: 'additive',
      },
    },
  });
};