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
    }
  ]
}

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 LAST tool message

toolCallId is compared against the tool_call_id of the last role: "tool" message in the request — regardless of whether that’s the overall last message. If no tool message is present in the history, toolCallId never matches. 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 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 now factors in turnIndex, hasToolResult, context, and sequenceIndex when deciding whether two fixtures truly collide, but it does not consider toolCallId, model, or predicate, so the warning may still fire when those discriminators are present. Treat it as advisory: if a runtime differentiator is in place, the fixtures won't actually shadow each other at match time. 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. Safe to ignore in the former case; investigate in the latter.
• 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

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 stream exactly 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

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.