#测试

// 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 extends RenderRouteTarget>(target: (Target & RouteTargetConstraint<Target>) | RouteTargetConstraint<Target>, options?: RenderRouteOptions<Target> | undefined) => Promise<RenderedRoute<Target>>
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 
renderRoute<"tool:library/summarize">(target: string, options?: RenderRouteOptions<"tool:library/summarize"> | undefined): Promise<RenderedRoute<"tool:library/summarize">>
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<"tool:library/summarize">.input?: unknown
The route's input: tool input, event payload, or script input — typed from the route's own schema once the id is registered.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 });
};

const { result } = await renderRoute('tool:library/summarize', {
  input: { title: 'Dune' },
});
const chapters: number | undefined = result?.chapters; // 无需强制类型转换

import { loadRouteModule, testManifest } from 'agent-bundle/test';

// schema 是 MCP 路由的契约；事件路由与脚本不导出 schema。
const mcpRoutes = Object.values(testManifest().routes)
  .filter((route) =>
    route.kind === 'tool' || route.kind === 'prompt' || route.kind === 'resource');

for (const route of mcpRoutes) {
  const module = await loadRouteModule(route.id);
  expect(module.inputSchema).toBeInstanceOf(z.ZodObject);
  expect(module.resultSchema).toBeInstanceOf(z.ZodObject);
  expect(module.config ?? {}).toEqual(route.config);
}

import { mountTestState, renderRoute } from 'agent-bundle/test';

import type { TopologyEvents, TopologyState } from '../../src/state.js';

const topology = await mountTestState<TopologyState, TopologyEvents>();
try {
  await renderRoute('event:session/start', {
    context: { ...topology.context(), host, workspace },
    input: start,
  });
  await renderRoute('event:tool/before', {
    context: { ...topology.context(), host, workspace },
    input: intent,
  });

  const snapshot = await topology.read(); // AgentStateSnapshot<TopologyState>
  expect(snapshot.state.activities).toHaveLength(1);
  const { notices } = await topology.notices(); // 那些渲染发布进去的 ledger
} finally {
  await topology.close();
}

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: <Name extends string, Server extends string = string>(tool: (Name & McpRouteNameConstraint<Name, "tool", Server>) | McpRouteNameConstraint<Name, "tool", Server>, options?: McpInvocationOptions<McpRouteInput<Name, "tool", Server>, Server> | 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.
tool is the wire name (find for the route tool:curator/find). Once
the project's routes are registered, a literal is checked against the
compiled tool names — of the literal server when one is passed, since
the session mounts only that server's routes — and input is typed from
that route's inputSchema (see
McpRouteNameConstraint
). The
projected structuredContent stays unknown: the wire carries it only for
object-valued documents, so the route's resultSchema output is not what
every call yields.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 
invokeMcpTool<"summarize", string>(tool: string, options?: McpInvocationOptions<unknown, string> | 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.
tool is the wire name (find for the route tool:curator/find). Once
the project's routes are registered, a literal is checked against the
compiled tool names — of the literal server when one is passed, since
the session mounts only that server's routes — and input is typed from
that route's inputSchema (see
McpRouteNameConstraint
). The
projected structuredContent stays unknown: the wire carries it only for
object-valued documents, so the route's resultSchema output is not what
every call yields.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 probe
process.stdout; the in-process harness defaults to piped output. The
same knob shapes the request.terminal the command observes (#511): a
synthetic 80×24 basic-color terminal on both streams, or two color-free
pipes. Inject context.terminal to choose other values.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: ContractRouteFixtures
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<unknown>.input?: unknown
Valid input for the sweep invocation (tools/prompts; resources need none).input: { 
title: stringtitle: 'Dune' },
        
ContractRouteFixture<unknown>.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<unknown>.resultCompat?: ResultCompatPolicy | undefined
Declared serialized-result compatibility policy. REQUIRED for tool routes.resultCompat: 'additive',
      },
    },
  });
};