Fixtures

Fixtures define what the mock server returns. Each fixture has a match criteria and a response. Load them from JSON files, register them programmatically, or mix both approaches.

File Format

{
  "fixtures": [
    {
      "match": {
        "userMessage": "hello",
        "model": "gpt-4"
      },
      "response": {
        "content": "Hello!"
      },
      "latency": 200,
      "chunkSize": 10
    }
  ]
}

A fixture file may also hold an optional top-level mcpFakes key, which scripts MCP tool answers for one test scenario next to its LLM turns. A file may hold fixtures, mcpFakes, or both. See MCPMock: Scenario fakes.

Match Fields

Matching Semantics

These are the rules the router uses to pick a fixture for a given request. All fields on match are AND-ed — every one must pass for the fixture to be selected.

1. userMessage matches only the LAST user message

userMessage is compared against the content of the last message with role: "user" in the request. Earlier user messages in the conversation history are ignored. A request that contains ten turns of prior history plus one new user turn only matches against that final turn — never against anything earlier.

This is the single rule that trips people up most often. If you need to differentiate conversations by earlier context (for example, to return a different response on the second round of a tool-using conversation), use toolCallId, sequenceIndex, or a predicate instead of piling keywords into userMessage. See Multi-Turn Conversations for the tool-round idiom.

2. toolCallId matches the overall last message

toolCallId matches only when the request’s overall last message is a role: "tool" result whose tool_call_id equals the given value. This mirrors the API contract: a tool result is the last message only while the model is answering that tool round. If the last message is anything else — a newer user turn, or no tool result at all — toolCallId never matches, so a stale tool round can’t shadow userMessage matchers. This is the same overall-last-message rule as toolResultContains. See Multi-Turn Conversations for the tool-round idiom.

3. First match wins, in file order

Fixtures are evaluated in the order they were registered. The first fixture whose match criteria all pass is returned — subsequent fixtures are not consulted. For file-loaded fixtures, that means order within the JSON array. For loadFixtureDir(), files are loaded in sorted filename order, so a 00-catchall.json loaded before 10-specific.json will shadow the specific fixture. Put more specific fixtures before broader ones.

sequenceIndex lets a single pattern return different responses on repeated matches — see Sequential Responses.

4. Substring by default, exact when a requestTransform is set

By default, string userMessage (and inputText) match via String.includes — userMessage: "hello" matches "say hello world". Pass a RegExp when you need pattern matching. When a requestTransform is configured, this behavior flips to strict equality — see the next paragraph for why.

If the router is configured with a requestTransform (typically used to strip dynamic data like timestamps or UUIDs from the request before matching), string userMessage, systemMessage, and inputText flip to strict equality (===). The rationale: transforms normalize requests to a canonical form, and once normalized, the sensible comparison is exact — substring matching on a normalized string is more likely to hide bugs than catch flexible input.

5. Validation warnings surface shadowing at load time

validateFixtures() runs when fixtures are loaded and emits warnings for common shadowing mistakes:

• Duplicate userMessage — two fixtures with the same string userMessage produce a warning of the form duplicate userMessage 'hello' — shadows fixture 0, where 'hello' is the duplicated message and 0 is the zero-based index of the earlier fixture being shadowed. This is advisory, not a hard error: the check factors in every match discriminator the router gates on when deciding whether two fixtures truly collide — userMessage, systemMessage, inputText, toolCallId, toolResultContains, toolName, model, responseFormat, endpoint, context, sequenceIndex, turnIndex, and hasToolResult — so two fixtures that differ on any one of them do not trigger the warning. A predicate is a function that cannot be compared for equivalence, so any fixture carrying one is keyed by its own identity: it is treated as unconditionally distinct and never reported as a duplicate (and two fixtures with distinct predicates are likewise treated as distinct). Only fixtures with no differentiator at all will truly shadow on match — that's the case where the second is never reached because the first wins. That is the case worth investigating.
• Catch-all not last — a fixture with an empty match (no discriminator fields) matches everything. If it is not the final fixture, every fixture after it is unreachable. The warning is of the form empty match acts as catch-all but is not the last fixture — shadows fixtures 3+, where 3 is the zero-based index of the first shadowed fixture (i.e. every fixture from that index onward).

6. Use predicate for arbitrary logic

When the built-in match fields can't express the condition you need, a predicate function receives the full request and returns a boolean. It is the escape hatch for anything from inspecting the assistant's prior tool call arguments to gating on system-prompt content. Predicates are programmatic-only — JSON fixture files cannot serialize functions.

mock.on(
  { predicate: (req) => req.messages.at(-1)?.role === "tool" },
  { content: "Done!" }
);

Response Types

GPT-Live transcripts

A Live fixture uses match.endpoint: "openai-live" and response: { live: transcript, liveTiming: "immediate" }. It describes a complete conversation on GET /v1/live/sessions. The WebSocket guide explains the connection and session commands.

import { readFileSync } from "node:fs";
import { LLMock, type LiveTranscript } from "@copilotkit/aimock";

// Run from the aimock repository. Choose one mode per server.
const path = "./fixtures/openai-live-client.json";
const mock = new LLMock();
mock.loadFixtureFile(path);
await mock.start();
// Connect your application to mock.url at /v1/live/sessions.
// After the conversation, close its socket and await mock.stop().

// Alternative registration on a separate server:
const document = JSON.parse(readFileSync(path, "utf8"));
const transcript: LiveTranscript = document.fixtures[0].response.live;
const builderMock = new LLMock();
builderMock.onLive({ model: "gpt-live-1" }, transcript);

The repository includes fixtures/openai-live-client.json and fixtures/openai-live-managed.json. Both match the same endpoint and model, so load one per server. These examples contain authored events and synthetic PCM samples. Their timing and usage values are illustrative. They are not provider recordings or speech. The builder takes the transcript directly and defaults to recorded timing. The example files explicitly select immediate timing.

Transcript format

The final close reason must be close_requested or remote_hangup. Partial captures and error probes are rejected. Server configuration snapshots must agree with startup and accepted updates. Only managed backend instructions updates are supported. Mode and audio format cannot change during a session.

Causal barriers and PCM chunks

A server barrier uses { command, audioBytes } to identify required client input. command counts accepted non-audio commands, including startup. audioBytes counts decoded input bytes since that command. Barriers must increase or stay equal and must refer to preceding client input. A server event cannot run before client input that defines an identifier it references.

Replay compares decoded input PCM bytes across adjacent audio appends with identical metadata. Clients can split or combine these chunks at sample boundaries. Each PCM16 sample uses two bytes. A non-audio command or metadata change ends the run. Annotated audio commands retain their original frame boundary. Rechunking cannot move bytes across these boundaries. Aimock replays fixture output audio and does not synthesize speech from transcript text.

Identifier bindings

A binding's pointer is a JSON Pointer relative to its entry's event. action is "define" or "reference". owner is "client" or "server". One symbolic name connects each definition to its later references. Replay creates fresh server identifiers for each connection. Clients must use the identifiers received on that connection, including delegation IDs and tool-call IDs.

The limited origin: "imported-context" exception defines a first-seen server response ID at /event/response/previous_response_id in a response lifecycle event. This represents earlier context outside the capture. It applies only to a non-null identifier without an earlier definition. Later occurrences reference that same name. Other forward references remain invalid, and null values have no binding.

Replay timing

liveTiming: "recorded" is the default. Replay uses each server event's atMs offset from accepted startup, divided by the fixture's replaySpeed, or the server value when omitted (default 1). A speed of 2 halves those offsets. liveTiming: "immediate" removes the recorded delays. Both modes preserve server order and wait for causal barriers. Faster timing does not bypass required client commands, tool results, or input audio. Session limits and timeouts still apply. See Record & Replay for capture and retention.

Tool argument JSON

Malformed JSON in a tool call's arguments is no longer silently replaced with {}. The response depends on how the selected API carries arguments:

• String arguments: The malformed string is sent unchanged. This includes Anthropic Messages, Bedrock InvokeModel, Bedrock Converse, and Gemini Interactions streaming argument deltas, plus Cohere's streaming and non-streaming arguments. A client or SDK may reject the malformed JSON when it parses the string.
• Object arguments: Malformed JSON produces an explicit error before response content is sent. This applies to non-streaming Anthropic Messages, Bedrock InvokeModel, Bedrock Converse, and Gemini Interactions, and to Gemini, Gemini Live, and Ollama. HTTP requests return status 500; Gemini Live sends an error on the existing WebSocket connection.

Valid JSON retains its existing behavior, including arrays, primitives, and null. Empty or omitted legacy tool-call arguments still default to {}; whitespace-only strings are malformed JSON. Fixture validation is unchanged: validateFixtures() can still reject malformed arguments before replay, and ordered tool-call blocks still require an arguments field.

Ordered blocks (tool-first & interleaved streaming)

By default a Content + Tool Calls response streams its text first, then its tool calls. To control that order — for example to emit a tool call before any text (“tool-first”), or to interleave text and tool calls — add an optional blocks array. Each entry is one of:

• { "type": "text", "text": "..." } — a text segment
• { "type": "toolCall", "name": "...", "arguments": ..., "id": "..." } — a tool call (id optional; arguments accepts an object or string, same auto-stringify rules as elsewhere)

When blocks is present it takes precedence over the content and toolCalls fields for stream ordering: the blocks are streamed in array order. When blocks is absent, legacy { content, toolCalls } fixtures with valid JSON arguments stream as before — text-first, byte-identical to prior releases. The field is purely additive.

Blocks-only fixtures (first-class)

A fixture can be written with only a blocks array — no content or toolCalls needed. A non-empty blocks array is a first-class response shape: the builders derive the aggregate text and tool calls from the blocks themselves, and validateFixtures() accepts it without requiring the legacy fields. This is the cleanest way to author a tool-first or interleaved response — you express the order once, in one place, with no duplicated aggregate to keep in sync.

{
  "blocks": [
    { "type": "toolCall", "name": "get_weather", "arguments": { "city": "SF" }, "id": "call_1" },
    { "type": "text", "text": "Here is the weather." }
  ]
}

The example above streams the get_weather tool call before the text, with no separate content / toolCalls fields. For an interleaved stream, list blocks in the desired order, e.g. [toolCall, text, toolCall].

You may still supply content and toolCalls alongside blocks if you want an explicit aggregate — for example to assert a specific merged shape independently of the order. Both forms are supported; blocks always wins for stream ordering.

Per-provider observability

How faithfully “tool-first” / interleaved order is observable depends on each provider's wire protocol — and, for some providers, on whether the request is streaming. The mock always emits in block order; what a client can reconstruct from the result varies. A shape is Full when the wire carries the blocks in a single positionally-ordered structure (indexed content blocks, ordered output items, ordered steps); it is Non-observable when text and tool calls land in separate top-level fields that the client merges without a shared order. It is Partial when block order is carried on the wire (chunk arrival order) but the structure is not positionally indexed, so some clients reassemble positionally rather than honoring arrival order — observable best-effort, not guaranteed. The classifications below were verified against each provider's builder.

Response Override Fields

Fixture responses can include optional fields to override auto-generated envelope values. These map correctly across all provider formats (OpenAI, Claude, Gemini, Responses API).

Fixture Options

Loading Fixtures

addFixturesFromJSON() accepts an array of fixture entries, either as a JSON string or as a parsed array. Fixture files use the { "fixtures": [...] } envelope shown above; load those files with loadFixtureFile().

Each JSON fixture needs an object-valued match. An explicit empty object ({}) remains a catch-all. Scalar and array values are invalid.

• File loading skips entries with scalar or array match values. It warns with the file path and original zero-based entry index, and retains valid siblings in order. This recovery does not apply to missing or null matches or other conversion errors.
• addFixturesFromJSON() throws a TypeError for an invalid match value. It adds none of the entries in that batch.
• POST /__aimock/fixtures returns HTTP 400 for an invalid match value. It adds none of the entries in that batch.
• aimock validate reports scalar or array match values as errors and exits with status 1. Its fixture count excludes those entries, while diagnostics retain their original source indices.

LLMock.loadFixtureFile(), LLMock.loadFixtureDir() and llmock --fixtures also load a file’s mcpFakes. When no mount serves a block’s mount path (default /mcp), aimock mounts an MCPMock there, so fakes need no other setup. The free functions loadFixtureFile() and loadFixturesFromDir() return LLM fixtures only and throw on a file with mcpFakes; use loadFixtureFileWithServices() or loadFixturesFromDirWithServices() for such files. See MCPMock: Scenario fakes.

From a file

const mock = new LLMock();
mock.loadFixtureFile("./fixtures/chat.json");
mock.loadFixtureFile("./fixtures/tools.json");

From a directory

// Loads all .json files in the directory (non-recursive)
mock.loadFixtureDir("./fixtures");

Context-scoped fixtures

{
  "fixtures": [
    {
      "match": { "userMessage": "hello", "context": "langgraph-python" },
      "response": { "content": "Hi from LangGraph!" }
    },
    {
      "match": { "userMessage": "hello" },
      "response": { "content": "Hi from the shared fallback!" }
    }
  ]
}

Requests with X-AIMock-Context: langgraph-python match the first fixture; all other requests fall through to the shared fixture.

Programmatically

// Shorthand methods
mock.onMessage("hello", { content: "Hi!" });
mock.onToolCall("get_weather", { content: "72F" });
mock.onEmbedding("my text", { embedding: [0.1, 0.2] });
mock.onImage("sunset", { image: { url: "https://example.com/sunset.png" } });
mock.onSpeech("hello", { audio: "SGVsbG8=" });
mock.onTranscription({ transcription: { text: "Hello" } });
mock.onVideo("cats", { video: { id: "vid-1", status: "completed", url: "https://example.com/cats.mp4" } });
mock.onJsonOutput("data", { key: "value" });
mock.onToolResult("call_123", { content: "Done" });

// Full fixture object
mock.addFixture({
  match: { userMessage: "hello", model: "gpt-4" },
  response: { content: "Hi!" },
  latency: 100,
  chunkSize: 5,
});

// Predicate-based routing
mock.on(
  { predicate: (req) => req.messages.at(-1)?.role === "tool" },
  { content: "Done!" }
);

Provider Support Matrix

^* Azure inherits OpenAI’s override support because Azure OpenAI routes through the OpenAI Chat Completions response format internally.

^† Gemini Interactions captures reasoning on record (its collapser assembles thought_summary deltas into reasoning), but its replay builders do not re-emit reasoning, so a replayed turn carries none.