@node-llm/testing 0.1.0 → 0.2.1

package/src/Mocker.ts

@@ -55,14 +55,56 @@ export interface MockerDebugInfo {
 
 const EXECUTION_METHODS = ["chat", "stream", "paint", "transcribe", "moderate", "embed"];
 
+export interface MockerOptions {
+  /**
+   * Enforce that every LLM call must have a corresponding mock.
+   * If true, unmocked calls throw an error.
+   */
+  strict?: boolean;
+}
+
+export interface MockCall {
+  method: string;
+  args: unknown[];
+  timestamp: number;
+  /**
+   * Convenience accessor for the primary input "prompt" of the call.
+   * - chat/stream: `messages`
+   * - embed/moderate: `input`
+   * - paint: `prompt`
+   * - transcribe: `file`
+   */
+  prompt?: unknown;
+}
+
 export class Mocker {
   private mocks: MockDefinition[] = [];
+  private _history: MockCall[] = [];
   public strict = false;
 
-  constructor() {
+  constructor(options: MockerOptions = {}) {
+    this.strict = !!options.strict;
     this.setupInterceptor();
   }
 
+  public get history(): MockCall[] {
+    return [...this._history];
+  }
+
+  public getCalls(method?: string): MockCall[] {
+    if (!method) return this.history;
+    return this._history.filter((c) => c.method === method);
+  }
+
+  public getLastCall(method?: string): MockCall | undefined {
+    const calls = this.getCalls(method);
+    return calls[calls.length - 1];
+  }
+
+  public resetHistory(): void {
+    this._history = [];
+  }
+
   public chat(query?: string | RegExp): this {
     return this.addMock("chat", (req: unknown) => {
       const chatReq = req as ChatRequest;
@@ -178,6 +220,7 @@ export class Mocker {
 
   public clear(): void {
     this.mocks = [];
+    this._history = [];
     providerRegistry.setInterceptor(undefined);
   }
 
@@ -207,6 +250,13 @@ export class Mocker {
           if (EXECUTION_METHODS.includes(methodName)) {
             if (methodName === "stream") {
               return async function* (this: Mocker, request: ChatRequest) {
+                this._history.push({
+                  method: methodName,
+                  args: [request],
+                  timestamp: Date.now(),
+                  prompt: request.messages
+                });
+
                 const matchingMocks = this.mocks.filter(
                   (m) => m.method === methodName && m.match(request)
                 );
@@ -234,6 +284,20 @@ export class Mocker {
 
             // Promise-based methods
             return (async (request: unknown) => {
+              const req = request as any;
+              let promptAttr: unknown;
+              if (methodName === "chat") promptAttr = req.messages;
+              else if (methodName === "embed" || methodName === "moderate") promptAttr = req.input;
+              else if (methodName === "paint") promptAttr = req.prompt;
+              else if (methodName === "transcribe") promptAttr = req.file;
+
+              this._history.push({
+                method: methodName,
+                args: [request],
+                timestamp: Date.now(),
+                prompt: promptAttr
+              });
+
               const matchingMocks = this.mocks.filter(
                 (m) => m.method === methodName && m.match(request)
               );
@@ -306,6 +370,6 @@ export class Mocker {
   }
 }
 
-export function mockLLM() {
-  return new Mocker();
+export function mockLLM(options: MockerOptions = {}) {
+  return new Mocker(options);
 }

package/src/Scrubber.ts

@@ -56,6 +56,36 @@ export class Scrubber {
       return val.map((v) => this.deepScrub(v));
     }
 
+    if (val instanceof Map) {
+      const newMap = new Map();
+      for (const [k, v] of val.entries()) {
+        const scrubbedKey = typeof k === "string" ? this.deepScrub(k) : k;
+        const scrubbedValue = this.deepScrub(v);
+        newMap.set(scrubbedKey, scrubbedValue);
+      }
+      return newMap;
+    }
+
+    if (val instanceof Set) {
+      const newSet = new Set();
+      for (const v of val.values()) {
+        newSet.add(this.deepScrub(v));
+      }
+      return newSet;
+    }
+
+    if (val instanceof Date) {
+      return new Date(val);
+    }
+
+    if (val instanceof RegExp) {
+      return new RegExp(val);
+    }
+
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(val)) {
+      return Buffer.from(val);
+    }
+
     if (val !== null && typeof val === "object") {
       const obj = val as Record<string, unknown>;
       const newObj: Record<string, unknown> = {};

package/src/Serializer.ts

@@ -0,0 +1,113 @@
+/**
+ * Handles serialization and deserialization of complex types that JSON.stringify/parse
+ * natively lose (Date, Map, Set, RegExp, Error, Infinity, NaN, Buffer).
+ */
+export class Serializer {
+  public static serialize(data: unknown, space?: string | number): string {
+    return JSON.stringify(data, Serializer.replacer, space);
+  }
+
+  public static deserialize<T = unknown>(json: string): T {
+    return JSON.parse(json, Serializer.reviver);
+  }
+
+  /**
+   * Deep clone that preserves types better than JSON.parse(JSON.stringify(x))
+   * Uses structuredClone if available (Node 17+), otherwise falls back to serialization.
+   */
+  public static clone<T>(data: T): T {
+    if (typeof globalThis.structuredClone === "function") {
+      try {
+        return globalThis.structuredClone(data);
+      } catch (err) {
+        // Fallback for types structuredClone might not handle or implementation quirks
+      }
+    }
+    return Serializer.deserialize(Serializer.serialize(data));
+  }
+
+  private static replacer(this: any, key: string, value: unknown): unknown {
+    const originalValue = this[key];
+
+    if (originalValue === Infinity) return { $type: "Infinity" };
+    if (originalValue === -Infinity) return { $type: "-Infinity" };
+    if (Number.isNaN(originalValue)) return { $type: "NaN" };
+
+    if (originalValue instanceof Date) {
+      return { $type: "Date", value: originalValue.toISOString() };
+    }
+
+    if (originalValue instanceof RegExp) {
+      return { $type: "RegExp", source: originalValue.source, flags: originalValue.flags };
+    }
+
+    if (originalValue instanceof Map) {
+      return { $type: "Map", value: Array.from(originalValue.entries()) };
+    }
+
+    if (originalValue instanceof Set) {
+      return { $type: "Set", value: Array.from(originalValue.values()) };
+    }
+
+    if (originalValue instanceof Error) {
+      return {
+        ...originalValue, // Capture literal properties attached to the error
+        $type: "Error",
+        name: originalValue.name,
+        message: originalValue.message,
+        stack: originalValue.stack,
+        cause: (originalValue as any).cause
+      };
+    }
+
+    // Handle Buffers (Node.js)
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(originalValue)) {
+      return { $type: "Buffer", value: originalValue.toString("base64") };
+    }
+
+    return value;
+  }
+
+  private static reviver(key: string, value: unknown): unknown {
+    if (value && typeof value === "object" && "$type" in value) {
+      const typedValue = value as { $type: string; value?: any; [key: string]: any };
+
+      switch (typedValue.$type) {
+        case "Date":
+          return new Date(typedValue.value);
+        case "RegExp":
+          return new RegExp(typedValue.source, typedValue.flags);
+        case "Map":
+          return new Map(typedValue.value);
+        case "Set":
+          return new Set(typedValue.value);
+        case "Infinity":
+          return Infinity;
+        case "-Infinity":
+          return -Infinity;
+        case "NaN":
+          return NaN;
+        case "Error": {
+          const err = new Error(typedValue.message);
+          err.name = typedValue.name;
+          if (typedValue.stack) err.stack = typedValue.stack;
+          if (typedValue.cause) (err as any).cause = typedValue.cause;
+          // Restore other properties
+          for (const k in typedValue) {
+            if (["$type", "name", "message", "stack", "cause"].includes(k)) continue;
+            (err as any)[k] = typedValue[k];
+          }
+          return err;
+        }
+        case "Buffer":
+          if (typeof Buffer !== "undefined") {
+            return Buffer.from(typedValue.value, "base64");
+          }
+          return typedValue.value;
+        default:
+          return value;
+      }
+    }
+    return value;
+  }
+}

package/src/vcr.ts

@@ -2,12 +2,13 @@ import { Provider, providerRegistry } from "@node-llm/core";
 import fs from "node:fs";
 import path from "node:path";
 import { Scrubber } from "./Scrubber.js";
+import { Serializer } from "./Serializer.js";
 
 // Internal state for nested scoping (Feature 12)
 const currentVCRScopes: string[] = [];
 
 // Try to import Vitest's expect to get test state
-let vitestExpect: any;
+let vitestExpect: { getState?: () => { currentTestName?: string } } | undefined;
 try {
   // @ts-ignore
   import("vitest").then((m) => {
@@ -21,9 +22,9 @@ export type VCRMode = "record" | "replay" | "auto" | "passthrough";
 
 export interface VCRInteraction {
   method: string;
-  request: any;
-  response: any;
-  chunks?: any[];
+  request: unknown;
+  response: unknown;
+  chunks?: unknown[];
 }
 
 export interface VCRCassette {
@@ -40,11 +41,13 @@ export interface VCRCassette {
 
 export interface VCROptions {
   mode?: VCRMode;
-  scrub?: (data: any) => any;
+  scrub?: (data: unknown) => unknown;
   cassettesDir?: string;
   scope?: string | string[]; // Allow single or multiple scopes
   sensitivePatterns?: RegExp[];
   sensitiveKeys?: string[];
+  /** @internal - For testing VCR library itself. Bypasses CI recording check. */
+  _allowRecordingInCI?: boolean;
 }
 
 export class VCR {
@@ -95,9 +98,10 @@ export class VCR {
     const initialMode = mergedOptions.mode || (process.env.VCR_MODE as VCRMode) || "auto";
     const isCI = !!process.env.CI;
     const exists = fs.existsSync(this.filePath);
+    const allowRecordingInCI = mergedOptions._allowRecordingInCI === true;
 
-    // CI Enforcement
-    if (isCI) {
+    // CI Enforcement (can be bypassed for VCR library's own unit tests)
+    if (isCI && !allowRecordingInCI) {
       if (initialMode === "record") {
         throw new Error(`VCR[${name}]: Recording cassettes is not allowed in CI.`);
       }
@@ -136,7 +140,7 @@ export class VCR {
       if (!exists) {
         throw new Error(`VCR[${name}]: Cassette not found at ${this.filePath}`);
       }
-      this.cassette = JSON.parse(fs.readFileSync(this.filePath, "utf-8"));
+      this.cassette = Serializer.deserialize(fs.readFileSync(this.filePath, "utf-8"));
     } else {
       this.cassette = {
         name,
@@ -167,7 +171,7 @@ export class VCR {
         this.cassette.metadata.duration = duration;
       }
 
-      fs.writeFileSync(this.filePath, JSON.stringify(this.cassette, null, 2));
+      fs.writeFileSync(this.filePath, Serializer.serialize(this.cassette, 2));
     }
     providerRegistry.setInterceptor(undefined);
   }
@@ -178,9 +182,9 @@ export class VCR {
 
   public async execute(
     method: string,
-    originalMethod: (...args: any[]) => Promise<any>,
-    request: any
-  ): Promise<any> {
+    originalMethod: (...args: unknown[]) => Promise<unknown>,
+    request: unknown
+  ): Promise<unknown> {
     if (this.mode === "replay") {
       const interaction = this.cassette.interactions[this.interactionIndex++];
       if (!interaction) {
@@ -206,9 +210,9 @@ export class VCR {
 
   public async *executeStream(
     method: string,
-    originalMethod: (...args: any[]) => AsyncIterable<any>,
-    request: any
-  ): AsyncIterable<any> {
+    originalMethod: (...args: unknown[]) => AsyncIterable<unknown>,
+    request: unknown
+  ): AsyncIterable<unknown> {
     if (this.mode === "replay") {
       const interaction = this.cassette.interactions[this.interactionIndex++];
       if (!interaction || !interaction.chunks) {
@@ -221,7 +225,7 @@ export class VCR {
     }
 
     const stream = originalMethod(request);
-    const chunks: any[] = [];
+    const chunks: unknown[] = [];
 
     for await (const chunk of stream) {
       if (this.mode === "record") chunks.push(this.clone(chunk));
@@ -240,12 +244,8 @@ export class VCR {
     }
   }
 
-  private clone(obj: any) {
-    try {
-      return JSON.parse(JSON.stringify(obj));
-    } catch {
-      return obj;
-    }
+  private clone(obj: unknown): unknown {
+    return Serializer.clone(obj);
   }
 
   private slugify(text: string): string {
@@ -271,7 +271,7 @@ export function setupVCR(name: string, options: VCROptions = {}) {
         const method = prop.toString();
 
         if (typeof originalValue === "function" && EXECUTION_METHODS.includes(method)) {
-          return function (...args: any[]) {
+          return function (...args: unknown[]) {
             if (method === "stream") {
               return vcr.executeStream(method, originalValue.bind(target), args[0]);
             }
@@ -297,14 +297,20 @@ export function withVCR(
   options: VCROptions,
   fn: () => Promise<void>
 ): () => Promise<void>;
-export function withVCR(...args: any[]): () => Promise<void> {
+export function withVCR(
+  ...args: [
+    (() => Promise<void>) | string | VCROptions,
+    ((() => Promise<void>) | VCROptions)?,
+    (() => Promise<void>)?
+  ]
+): () => Promise<void> {
   // Capture scopes at initialization time
   const capturedScopes = [...currentVCRScopes];
 
   return async function () {
     let name: string | undefined;
     let options: VCROptions = {};
-    let fn: () => Promise<void>;
+    let fn: (() => Promise<void>) | undefined;
 
     if (typeof args[0] === "function") {
       fn = args[0];
@@ -318,7 +324,11 @@ export function withVCR(...args: any[]): () => Promise<void> {
       }
     } else {
       options = args[0] || {};
-      fn = args[1];
+      fn = args[1] as (() => Promise<void>) | undefined;
+    }
+
+    if (!fn) {
+      throw new Error("VCR: No test function provided.");
     }
 
     // Pass captured inherited scopes if not explicitly overridden
@@ -326,7 +336,7 @@ export function withVCR(...args: any[]): () => Promise<void> {
       options.scope = capturedScopes;
     }
 
-    if (!name && vitestExpect) {
+    if (!name && vitestExpect?.getState) {
       const state = vitestExpect.getState();
       name = state.currentTestName || "unnamed-test";
     }

package/test/cassettes/handles-rich-types.json

@@ -0,0 +1,38 @@
+{
+  "name": "Handles Rich Types",
+  "version": "1.0",
+  "metadata": {
+    "recordedAt": "2026-01-26T14:26:32.372Z",
+    "duration": 5
+  },
+  "interactions": [
+    {
+      "method": "chat",
+      "request": {
+        "model": "mock-model",
+        "messages": [
+          {
+            "role": "user",
+            "content": "Hello"
+          }
+        ],
+        "max_tokens": 4096,
+        "headers": {},
+        "requestTimeout": 30000,
+        "createdAt": {},
+        "meta": {
+          "$type": "Map",
+          "value": [["key", "value"]]
+        }
+      },
+      "response": {
+        "content": "Response to Hello",
+        "usage": {
+          "input_tokens": 10,
+          "output_tokens": 10,
+          "total_tokens": 20
+        }
+      }
+    }
+  ]
+}

package/test/unit/__snapshots__/mocker_snapshots.test.ts.snap

@@ -0,0 +1,12 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Mocker Feature: Prompt Snapshots > Snapshots chat messages 1`] = `
+[
+  {
+    "content": "Hello",
+    "role": "user",
+  },
+]
+`;
+
+exports[`Mocker Feature: Prompt Snapshots > Snapshots embedding input 1`] = `"text"`;

package/test/unit/dx.test.ts

@@ -70,7 +70,7 @@ describe("VCR Feature 5 & 6: DX Sugar & Auto-Naming", () => {
     configureVCR({ cassettesDir: GLOBAL_DIR });
 
     // 2. Run a test relying on global dir (explicit record mode to create cassette)
-    await withVCR("global-dir-test", { mode: "record" }, async () => {
+    await withVCR("global-dir-test", { mode: "record", _allowRecordingInCI: true }, async () => {
       const llm = NodeLLM.withProvider("mock-provider");
       await llm.chat().ask("global dir test");
     })();

package/test/unit/mocker_history.test.ts

@@ -0,0 +1,115 @@
+import { test, expect, describe, beforeEach, afterEach } from "vitest";
+import { mockLLM } from "../../src/Mocker.js";
+import { NodeLLM, providerRegistry, Provider } from "@node-llm/core";
+import { MockProvider } from "../helpers/MockProvider.js";
+
+describe("Mocker Feature: Call History", () => {
+  let mocker: ReturnType<typeof mockLLM>;
+
+  beforeEach(() => {
+    providerRegistry.register("mock-provider", () => new MockProvider() as unknown as Provider);
+    mocker = mockLLM();
+  });
+
+  afterEach(() => {
+    mocker.clear();
+  });
+
+  test("Records chat calls in history", async () => {
+    mocker.chat("Hello").respond("Hi");
+    mocker.chat("Bye").respond("Goodbye");
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.chat().ask("Hello");
+    await llm.chat().ask("Bye");
+
+    expect(mocker.history.length).toBe(2);
+    expect(mocker.history[0]!.method).toBe("chat");
+    expect((mocker.history[0]!.args[0] as any).messages[0].content).toBe("Hello");
+    expect((mocker.history[1]!.args[0] as any).messages[0].content).toBe("Bye");
+  });
+
+  test("Records streaming calls in history", async () => {
+    mocker.chat("Stream me").stream(["chunk1", "chunk2"]);
+    const llm = NodeLLM.withProvider("mock-provider");
+
+    const stream = llm.chat().stream("Stream me");
+    for await (const _ of stream) {
+      /* consume */
+    }
+
+    expect(mocker.history.length).toBe(1);
+    expect(mocker.history[0]!.method).toBe("stream");
+    expect((mocker.history[0]!.args[0] as any).messages[0].content).toBe("Stream me");
+  });
+
+  test("getCalls filters by method", async () => {
+    mocker.chat("ChatCall").respond("OK");
+    mocker.embed("EmbedCall").respond({ vectors: [[0.1]] });
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.chat().ask("ChatCall");
+    await llm.embed("EmbedCall");
+
+    const chatCalls = mocker.getCalls("chat");
+    const embedCalls = mocker.getCalls("embed");
+
+    expect(chatCalls.length).toBe(1);
+    expect(chatCalls[0]!.method).toBe("chat");
+
+    expect(embedCalls.length).toBe(1);
+    expect(embedCalls[0]!.method).toBe("embed");
+
+    expect(mocker.history.length).toBe(2);
+  });
+
+  test("getLastCall retrieves the most recent call", async () => {
+    mocker.chat("First").respond("1");
+    mocker.chat("Second").respond("2");
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.chat().ask("First");
+    await llm.chat().ask("Second");
+
+    const last = mocker.getLastCall();
+    expect(last).toBeDefined();
+    expect((last?.args[0] as any).messages[0].content).toBe("Second");
+  });
+
+  test("getLastCall with method filtering checks types", async () => {
+    mocker.embed("Embed").respond({ vectors: [[1]] });
+    mocker.chat("Chat").respond("Hi");
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.embed("Embed");
+    await llm.chat().ask("Chat");
+
+    const lastEmbed = mocker.getLastCall("embed");
+    expect(lastEmbed).toBeDefined();
+    expect(lastEmbed?.method).toBe("embed");
+
+    const lastChat = mocker.getLastCall("chat");
+    expect(lastChat).toBeDefined();
+    expect(lastChat?.method).toBe("chat");
+  });
+
+  test("resetHistory clears history but preserves mocks", async () => {
+    mocker.chat("Preserved").respond("Still here");
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.chat().ask("Preserved");
+
+    expect(mocker.history.length).toBe(1);
+
+    mocker.resetHistory();
+
+    expect(mocker.history.length).toBe(0);
+
+    // Mocks should still work
+    const res = await llm.chat().ask("Preserved");
+    expect(res.content).toBe("Still here");
+
+    // New history recorded
+    expect(mocker.history.length).toBe(1);
+  });
+});

package/test/unit/mocker_snapshots.test.ts

@@ -0,0 +1,48 @@
+import { test, expect, describe, afterEach, beforeEach } from "vitest";
+import { mockLLM } from "../../src/Mocker.js";
+import { NodeLLM, providerRegistry, Provider } from "@node-llm/core";
+import { MockProvider } from "../helpers/MockProvider.js";
+
+describe("Mocker Feature: Prompt Snapshots", () => {
+  let mocker: ReturnType<typeof mockLLM>;
+
+  beforeEach(() => {
+    providerRegistry.register("mock-provider", () => new MockProvider() as unknown as Provider);
+    mocker = mockLLM();
+  });
+
+  afterEach(() => {
+    mocker.clear();
+  });
+
+  test("Snapshots chat messages", async () => {
+    mocker.chat("Hello").respond("Hi");
+
+    // Test basic chat snapshot
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.chat().ask("Hello");
+
+    const lastCall = mocker.getLastCall();
+    expect(lastCall).toBeDefined();
+    // Snapshot should contain just the user message
+    expect(lastCall!.prompt).toMatchSnapshot();
+  });
+
+  test("Snapshots embedding input", async () => {
+    mocker.embed("text").respond({ vectors: [[0.1]] });
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.embed("text");
+
+    expect(mocker.getLastCall()?.prompt).toMatchSnapshot();
+  });
+
+  test("Snapshots paint prompt", async () => {
+    mocker.paint("A sunset").respond({ url: "img.png" });
+
+    const llm = NodeLLM.withProvider("mock-provider");
+    await llm.paint("A sunset");
+
+    expect(mocker.getLastCall()?.prompt).toBe("A sunset");
+  });
+});

package/test/unit/scoping.test.ts

@@ -29,10 +29,14 @@ describe("VCR Feature 12: Hierarchical Scoping", () => {
     await describeVCR(LEVEL_1, () => {
       return describeVCR(LEVEL_2, async () => {
         // Use explicit mode: "record" to test cassette creation in temp dir
-        const testFn = withVCR(TEST_NAME, { mode: "record" }, async () => {
-          const llm = NodeLLM.withProvider("mock-provider");
-          await llm.chat().ask("Trigger record");
-        });
+        const testFn = withVCR(
+          TEST_NAME,
+          { mode: "record", _allowRecordingInCI: true },
+          async () => {
+            const llm = NodeLLM.withProvider("mock-provider");
+            await llm.chat().ask("Trigger record");
+          }
+        );
 
         await testFn();
       });