Class MockServer

Expand description

Mock LLM server that handles OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses API formats. Register rules with when(), point your SDK at url, and go.

Supports await using for automatic cleanup.

example

const server = new MockServer({ logLevel: "info" });
server.when("hello").reply("Hi there!");
await server.start();
// Point your client at server.url
await server.stop();

Constructors§

new MockServer(options?: MockServerOptions): MockServer

Properties§

§nextError: { ... }...

Queue a one-shot error for the very next request. Fires once then removes itself.

§when: { ... }...

Register a matching rule. Call .reply() on the result to set the response.

§whenTool: { ... }...

Shorthand for when({ toolName }).

§whenToolResult: { ... }...

Shorthand for when({ toolCallId }).

Accessors§

get history(): RequestHistory

Every request the server has handled.

get routes(): readonly string[]

The API routes registered on this server, e.g. ["/v1/chat/completions", ...].

get ruleCount(): number

Number of currently registered rules.

get rules(): readonly RuleSummary[]

A snapshot of all registered rules with their descriptions and remaining match counts.

get url(): string

The base URL the server is listening on, e.g. http://127.0.0.1:12345. Throws if the server hasn't started.

Methods§

"[asyncDispose]"(): Promise<void>

Calls stop(). Enables await using server = ... for automatic cleanup.

fallback(reply: Reply): void

Set the reply used when no rule matches.

defaultValue

"Mock server: no matching rule."

isDone(): boolean

Returns true when all rules with a .times() limit have been consumed.

load(pathOrDir: string): Promise<void>

Load rules from a .json5 file, a .ts/.js handler file, or a directory containing them.

reset(): void

Clear all rules, request history, and reset the fallback to its default.

start(port?: number): Promise<void>

Start listening. Pass 0 (the default) for a random port.

stop(): Promise<void>

Stop the server. Safe to call multiple times.