Project llm-mock-server

Type Aliases§

Source§

type FormatName = "openai" | "anthropic" | "responses"

The LLM API wire format that was detected for a request.

Source§

type LogLevel = keyof typeof LEVEL_PRIORITY

Log verbosity, from "none" (silent) through to "all" (everything).

Source§

type Match = string | RegExp | MatchObject | ((req: MockRequest) => boolean)

Determines whether a rule matches an incoming request.

A string does a case-insensitive substring match on the last user message. A RegExp gets tested against the last user message. A MatchObject checks multiple fields at once with AND logic. A function receives the normalised request and returns a boolean.

example
server.when("hello").reply("Hi!");
server.when(/explain (\w+)/i).reply("Here's an explanation.");
server.when({ model: /claude/, format: "anthropic" }).reply("Bonjour!");
server.when((req) => req.messages.length > 5).reply("Long conversation!");
Source§

type Reply = string | ReplyObject

A reply is either a plain string (turns into { text: "..." }) or a full reply object.

Source§

type Resolver = Reply | ((req: MockRequest) => Reply | Promise<Reply>)

A reply value or a function that produces one. Async functions are supported.

example
server.when("echo").reply((req) => `You said: ${req.lastMessage}`);
server.when("slow").reply(async (req) => {
  return { text: "Done thinking." };
});
Source§

type SequenceEntry = Reply | { options?: ReplyOptions; reply: Reply }

A single entry in a reply sequence. Can be a plain reply or a reply with per-step options.

example
server.when("step").replySequence([
  "Starting.",
  { reply: "Done.", options: { latency: 100 } },
]);

Functions§

Source§

createMock(options?: MockServerOptions): Promise<MockServer>

Create a server and start it in one go.

example
const server = await createMock({ port: 0, logLevel: "info" });
server.when("hello").reply("Hi!");
// run your tests
await server.stop();

Classes§

MockServer

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.

RequestHistory

Records every request the server handles. Iterable and has fluent query methods for test assertions.

Interfaces§

ErrorReply

An HTTP error response. The server returns this status code with a format-appropriate body.

Handler

The shape of a handler file's default export. You can export a single handler or an array of them.

MatchObject

A structured matcher. Every field you set must match for the rule to fire.

Message

A single conversation message, normalised across all supported formats.

MockRequest

A normalised view of an incoming request, regardless of the original wire format. This is what rule matchers and resolvers receive.

MockServerOptions

Options for constructing a MockServer or calling createMock().

PendingRule

Returned by when(). Call .reply() or .replySequence() on it to complete the rule.

RecordedRequest

A recorded request with the rule that matched and when it happened.

ReplyObject

A structured reply. Text, reasoning, tool calls, usage, and errors are all optional.

ReplyOptions

Per-rule streaming options. Merged with server-level defaults, with per-rule values winning.

RuleHandle

A handle to a registered rule. All methods return this for chaining.

RuleSummary

A summary of a registered rule, for inspection via server.rules.

ToolCall

A tool call in the mock response.

ToolDef

A tool definition from the request's tools array, normalised across formats.