@node-llm/testing 0.1.0 → 0.2.0

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();
       });

package/test/unit/scrubbing.test.ts

@@ -17,7 +17,7 @@ describe("VCR Feature 4: Automatic Scrubbing", () => {
     CASSETTE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "vcr-scrub-test-"));
     CASSETTE_PATH = path.join(CASSETTE_DIR, `${CASSETTE_NAME}.json`);
     mock = new MockProvider();
-    providerRegistry.register("mock-provider", () => mock);
+    providerRegistry.register("mock-provider", () => mock as any);
   });
 
   afterEach(() => {
@@ -29,7 +29,11 @@ describe("VCR Feature 4: Automatic Scrubbing", () => {
   });
 
   test("Automatically scrubs API keys and sensitive JSON keys", async () => {
-    const vcr = setupVCR(CASSETTE_NAME, { mode: "record", cassettesDir: CASSETTE_DIR });
+    const vcr = setupVCR(CASSETTE_NAME, {
+      mode: "record",
+      cassettesDir: CASSETTE_DIR,
+      _allowRecordingInCI: true
+    });
     const llm = NodeLLM.withProvider("mock-provider");
 
     // 1. Trigger request with secrets
@@ -50,6 +54,7 @@ describe("VCR Feature 4: Automatic Scrubbing", () => {
     const vcr = setupVCR(CASSETTE_NAME, {
       mode: "record",
       cassettesDir: CASSETTE_DIR,
+      _allowRecordingInCI: true,
       scrub: (data: unknown) => {
         // Deep string replacement on the whole interaction object
         return JSON.parse(JSON.stringify(data).replace(/sensitive-info/g, "XXXX"));
@@ -69,6 +74,7 @@ describe("VCR Feature 4: Automatic Scrubbing", () => {
     const vcr = setupVCR("custom-scrub-config", {
       mode: "record",
       cassettesDir: CASSETTE_DIR,
+      _allowRecordingInCI: true,
       sensitiveKeys: ["user_email", "internal_id"],
       sensitivePatterns: [/secret-project-[a-z]+/g]
     });
@@ -90,6 +96,7 @@ describe("VCR Feature 4: Automatic Scrubbing", () => {
     const vcr = setupVCR("defaults-plus-custom", {
       mode: "record",
       cassettesDir: CASSETTE_DIR,
+      _allowRecordingInCI: true,
       sensitiveKeys: ["custom_field"]
     });
 

package/test/unit/serializer.test.ts

@@ -0,0 +1,81 @@
+import { test, expect, describe } from "vitest";
+import { Serializer } from "../../src/Serializer.js";
+
+describe("Serializer", () => {
+  test("Handles Date objects", () => {
+    const data = { date: new Date("2023-01-01T00:00:00.000Z") };
+    const serialized = Serializer.serialize(data);
+    const deserialized = Serializer.deserialize(serialized);
+    expect(deserialized).toEqual(data);
+    expect((deserialized as any).date).toBeInstanceOf(Date);
+  });
+
+  test("Handles Map objects", () => {
+    const data = {
+      map: new Map<string, string | number>([
+        ["key", "value"],
+        ["num", 123]
+      ])
+    };
+    const serialized = Serializer.serialize(data);
+    const deserialized = Serializer.deserialize(serialized);
+    expect(deserialized).toEqual(data);
+    expect((deserialized as any).map).toBeInstanceOf(Map);
+    expect((deserialized as any).map.get("key")).toBe("value");
+  });
+
+  test("Handles Set objects", () => {
+    const data = { set: new Set([1, 2, 3, "four"]) };
+    const serialized = Serializer.serialize(data);
+    const deserialized = Serializer.deserialize(serialized);
+    expect(deserialized).toEqual(data);
+    expect((deserialized as any).set).toBeInstanceOf(Set);
+    expect((deserialized as any).set.has("four")).toBe(true);
+  });
+
+  test("Handles RegExp objects", () => {
+    const data = { regex: /abc/gi };
+    const serialized = Serializer.serialize(data);
+    const deserialized = Serializer.deserialize(serialized);
+    expect(deserialized).toEqual(data);
+    expect((deserialized as any).regex).toBeInstanceOf(RegExp);
+    expect((deserialized as any).regex.flags).toContain("g");
+    expect((deserialized as any).regex.flags).toContain("i");
+  });
+
+  test("Handles Error objects", () => {
+    const err = new Error("Test error");
+    err.name = "CustomError";
+    (err as any).customProp = "customValue";
+
+    const data = { error: err };
+    const serialized = Serializer.serialize(data);
+    const deserialized: any = Serializer.deserialize(serialized);
+
+    expect(deserialized.error).toBeInstanceOf(Error);
+    expect(deserialized.error.message).toBe("Test error");
+    expect(deserialized.error.name).toBe("CustomError");
+    expect(deserialized.error.customProp).toBe("customValue");
+    expect(deserialized.error.stack).toBeDefined();
+  });
+
+  test("Handles Buffer objects", () => {
+    if (typeof Buffer === "undefined") return; // Skip in browser-like envs if any
+    const data = { buf: Buffer.from("Hello World") };
+    const serialized = Serializer.serialize(data);
+    const deserialized: any = Serializer.deserialize(serialized);
+
+    expect(deserialized.buf).toBeInstanceOf(Buffer);
+    expect(deserialized.buf.toString()).toBe("Hello World");
+  });
+
+  test("Handles Infinity and NaN", () => {
+    const data = { inf: Infinity, negInf: -Infinity, nan: NaN };
+    const serialized = Serializer.serialize(data);
+    const deserialized: any = Serializer.deserialize(serialized);
+
+    expect(deserialized.inf).toBe(Infinity);
+    expect(deserialized.negInf).toBe(-Infinity);
+    expect(Number.isNaN(deserialized.nan)).toBe(true);
+  });
+});