@node-llm/testing 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## 0.1.0
+## [0.2.0] - 2026-01-26
+
+### Added
+
+- **Call Verification**: Added `mocker.history`, `mocker.getCalls()`, and `mocker.getLastCall()` for spy-style assertions.
+- **Prompt Snapshots**: Added `mocker.getLastCall().prompt` convenience accessor for snapshot testing of request structures.
+- **Rich Type Persistence**: VCR now faithfully records and replays `Date`, `Map`, `Set`, `Buffer`, `RegExp`, `Infinity`, `NaN`, and `Error` objects using a new Smart Serializer.
+- **Deep Scrubbing**: `Scrubber` now recurses into `Map` and `Set` collections to redact sensitive data.
+- **Modern Cloning**: Switched to `structuredClone` for high-performance in-memory operations.
+
+### Security
+
+- **Hardened Scrubbing**: Fixed potential leak where secrets inside nested Maps/Sets were skipped by the scrubber.
+
+### Improvements
+
+- **Documentation**: Added comprehensive "Testing" section to project documentation and `llms.txt`.
+- **Reliability**: VCR no longer corrupts binary data (Buffers) during recording.
+
+## [0.1.0]
+
+### Added
 
 - Initial release
 - VCR record/replay

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodeLLM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -116,6 +116,30 @@ mocker.paint(/a cat/i).respond({ url: "https://mock.com/cat.png" });
 mocker.embed("text").respond({ vectors: [[0.1, 0.2, 0.3]] });
 ```
 
+### Call Verification & History 🕵️‍♀️
+
+Inspect what requests were sent to your mock, enabling "spy" style assertions.
+
+```typescript
+// 1. Check full history
+const history = mocker.history;
+expect(history.length).toBe(1);
+
+// 2. Filter by method
+const chats = mocker.getCalls("chat");
+expect(chats[0].args[0].messages[0].content).toContain("Hello");
+
+// 3. Get the most recent call
+const lastEmbed = mocker.getLastCall("embed");
+expect(lastEmbed.args[0].input).toBe("text to embed");
+
+// 4. Reset history (keep mocks)
+mocker.resetHistory();
+
+// 5. Snapshot valid request structures
+expect(mocker.getLastCall().prompt).toMatchSnapshot();
+```
+
 ---
 
 ## 🛣️ Decision Tree: VCR vs Mocker
@@ -438,9 +462,6 @@ interface VCROptions {
 interface MockerOptions {
   // Enforce exact matching
   strict?: boolean;
-
-  // Enable verbose logging
-  debug?: boolean;
 }
 ```
 
@@ -481,6 +502,24 @@ interface MockerDebugInfo {
 }
 ```
 
+### MockCall
+
+```typescript
+interface MockCall {
+  // The method name ("chat", "stream", etc.)
+  method: string;
+
+  // The arguments passed to the method
+  args: unknown[];
+
+  // Timestamp of the call
+  timestamp: number;
+
+  // Convenience prompt accessor (e.g. messages, input text)
+  prompt?: unknown;
+}
+```
+
 ---
 
 ## 🏛️ Integration with @node-llm/orm

package/dist/Mocker.d.ts

@@ -31,10 +31,35 @@ export interface MockerDebugInfo {
     totalMocks: number;
     methods: string[];
 }
+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 declare class Mocker {
     private mocks;
+    private _history;
     strict: boolean;
-    constructor();
+    constructor(options?: MockerOptions);
+    get history(): MockCall[];
+    getCalls(method?: string): MockCall[];
+    getLastCall(method?: string): MockCall | undefined;
+    resetHistory(): void;
     chat(query?: string | RegExp): this;
     stream(chunks: string[] | ChatChunk[]): this;
     placeholder(query: string | RegExp): this;
@@ -54,5 +79,5 @@ export declare class Mocker {
     private getContentString;
     private setupInterceptor;
 }
-export declare function mockLLM(): Mocker;
+export declare function mockLLM(options?: MockerOptions): Mocker;
 //# sourceMappingURL=Mocker.d.ts.map

package/dist/Mocker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Mocker.d.ts","sourceRoot":"","sources":["../src/Mocker.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEjB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,YAAY,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAAwB;IAC9B,MAAM,UAAS;;IAMf,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAcnC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,GAAG,IAAI;IAU5C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAWzC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAmBjE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAQtC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IASrC,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IASxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI;IAUlD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,YAAY,CAAC,GAAG,IAAI;IAWxF;;;OAGG;IACI,YAAY,IAAI,eAAe;IAQ/B,KAAK,IAAI,IAAI;IAKpB,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,gBAAgB;CA6GzB;AAED,wBAAgB,OAAO,WAEtB"}
+{"version":3,"file":"Mocker.d.ts","sourceRoot":"","sources":["../src/Mocker.ts"],"names":[],"mappings":"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"}

package/dist/Mocker.js

@@ -2,10 +2,27 @@ import { providerRegistry } from "@node-llm/core";
 const EXECUTION_METHODS = ["chat", "stream", "paint", "transcribe", "moderate", "embed"];
 export class Mocker {
     mocks = [];
+    _history = [];
     strict = false;
-    constructor() {
+    constructor(options = {}) {
+        this.strict = !!options.strict;
         this.setupInterceptor();
     }
+    get history() {
+        return [...this._history];
+    }
+    getCalls(method) {
+        if (!method)
+            return this.history;
+        return this._history.filter((c) => c.method === method);
+    }
+    getLastCall(method) {
+        const calls = this.getCalls(method);
+        return calls[calls.length - 1];
+    }
+    resetHistory() {
+        this._history = [];
+    }
     chat(query) {
         return this.addMock("chat", (req) => {
             const chatReq = req;
@@ -124,6 +141,7 @@ export class Mocker {
     }
     clear() {
         this.mocks = [];
+        this._history = [];
         providerRegistry.setInterceptor(undefined);
     }
     addMock(method, matcher) {
@@ -151,6 +169,12 @@ export class Mocker {
                     if (EXECUTION_METHODS.includes(methodName)) {
                         if (methodName === "stream") {
                             return async function* (request) {
+                                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));
                                 const mock = matchingMocks[matchingMocks.length - 1];
                                 if (mock) {
@@ -177,6 +201,22 @@ export class Mocker {
                         }
                         // Promise-based methods
                         return (async (request) => {
+                            const req = request;
+                            let promptAttr;
+                            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));
                             const mock = matchingMocks[matchingMocks.length - 1];
                             if (mock) {
@@ -242,6 +282,6 @@ export class Mocker {
         });
     }
 }
-export function mockLLM() {
-    return new Mocker();
+export function mockLLM(options = {}) {
+    return new Mocker(options);
 }

package/dist/Scrubber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Scrubber.d.ts","sourceRoot":"","sources":["../src/Scrubber.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,UAInC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAC5C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,cAAc,CAAC,CAA6B;IACpD,OAAO,CAAC,iBAAiB,CAAW;IACpC,OAAO,CAAC,aAAa,CAAc;gBAEvB,OAAO,GAAE,eAAoB;IAazC;;OAEG;IACI,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAYpC,OAAO,CAAC,SAAS;CAuClB"}
+{"version":3,"file":"Scrubber.d.ts","sourceRoot":"","sources":["../src/Scrubber.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,UAInC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAC5C,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,cAAc,CAAC,CAA6B;IACpD,OAAO,CAAC,iBAAiB,CAAW;IACpC,OAAO,CAAC,aAAa,CAAc;gBAEvB,OAAO,GAAE,eAAoB;IAazC;;OAEG;IACI,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAYpC,OAAO,CAAC,SAAS;CAqElB"}

package/dist/Scrubber.js

@@ -42,6 +42,31 @@ export class Scrubber {
         if (Array.isArray(val)) {
             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;
             const newObj = {};

package/dist/Serializer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Handles serialization and deserialization of complex types that JSON.stringify/parse
+ * natively lose (Date, Map, Set, RegExp, Error, Infinity, NaN, Buffer).
+ */
+export declare class Serializer {
+    static serialize(data: unknown, space?: string | number): string;
+    static deserialize<T = unknown>(json: string): T;
+    /**
+     * Deep clone that preserves types better than JSON.parse(JSON.stringify(x))
+     * Uses structuredClone if available (Node 17+), otherwise falls back to serialization.
+     */
+    static clone<T>(data: T): T;
+    private static replacer;
+    private static reviver;
+}
+//# sourceMappingURL=Serializer.d.ts.map

package/dist/Serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.d.ts","sourceRoot":"","sources":["../src/Serializer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU;WACP,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;WAIzD,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAIvD;;;OAGG;WACW,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC;IAWlC,OAAO,CAAC,MAAM,CAAC,QAAQ;IA0CvB,OAAO,CAAC,MAAM,CAAC,OAAO;CA0CvB"}

package/dist/Serializer.js

@@ -0,0 +1,107 @@
+/**
+ * Handles serialization and deserialization of complex types that JSON.stringify/parse
+ * natively lose (Date, Map, Set, RegExp, Error, Infinity, NaN, Buffer).
+ */
+export class Serializer {
+    static serialize(data, space) {
+        return JSON.stringify(data, Serializer.replacer, space);
+    }
+    static deserialize(json) {
+        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.
+     */
+    static clone(data) {
+        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));
+    }
+    static replacer(key, value) {
+        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.cause
+            };
+        }
+        // Handle Buffers (Node.js)
+        if (typeof Buffer !== "undefined" && Buffer.isBuffer(originalValue)) {
+            return { $type: "Buffer", value: originalValue.toString("base64") };
+        }
+        return value;
+    }
+    static reviver(key, value) {
+        if (value && typeof value === "object" && "$type" in value) {
+            const typedValue = value;
+            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.cause = typedValue.cause;
+                    // Restore other properties
+                    for (const k in typedValue) {
+                        if (["$type", "name", "message", "stack", "cause"].includes(k))
+                            continue;
+                        err[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/dist/vcr.d.ts

@@ -1,9 +1,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 {
     name: string;
@@ -18,11 +18,13 @@ export interface VCRCassette {
 }
 export interface VCROptions {
     mode?: VCRMode;
-    scrub?: (data: any) => any;
+    scrub?: (data: unknown) => unknown;
     cassettesDir?: string;
     scope?: string | string[];
     sensitivePatterns?: RegExp[];
     sensitiveKeys?: string[];
+    /** @internal - For testing VCR library itself. Bypasses CI recording check. */
+    _allowRecordingInCI?: boolean;
 }
 export declare class VCR {
     private cassette;
@@ -35,8 +37,8 @@ export declare class VCR {
     get currentMode(): VCRMode;
     stop(): Promise<void>;
     private get interactionsCount();
-    execute(method: string, originalMethod: (...args: any[]) => Promise<any>, request: any): Promise<any>;
-    executeStream(method: string, originalMethod: (...args: any[]) => AsyncIterable<any>, request: any): AsyncIterable<any>;
+    execute(method: string, originalMethod: (...args: unknown[]) => Promise<unknown>, request: unknown): Promise<unknown>;
+    executeStream(method: string, originalMethod: (...args: unknown[]) => AsyncIterable<unknown>, request: unknown): AsyncIterable<unknown>;
     private clone;
     private slugify;
 }

package/dist/vcr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr.d.ts","sourceRoot":"","sources":["../src/vcr.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vcr.d.ts","sourceRoot":"","sources":["../src/vcr.ts"],"names":[],"mappings":"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"}

package/dist/vcr.js

@@ -2,6 +2,7 @@ import { 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 = [];
 // Try to import Vitest's expect to get test state
@@ -60,8 +61,9 @@ export class VCR {
         const initialMode = mergedOptions.mode || process.env.VCR_MODE || "auto";
         const isCI = !!process.env.CI;
         const exists = fs.existsSync(this.filePath);
-        // CI Enforcement
-        if (isCI) {
+        const allowRecordingInCI = mergedOptions._allowRecordingInCI === true;
+        // 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.`);
             }
@@ -95,7 +97,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 = {
@@ -123,7 +125,7 @@ export class VCR {
             if (this.cassette.metadata) {
                 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,12 +180,7 @@ export class VCR {
         }
     }
     clone(obj) {
-        try {
-            return JSON.parse(JSON.stringify(obj));
-        }
-        catch {
-            return obj;
-        }
+        return Serializer.clone(obj);
     }
     slugify(text) {
         return text
@@ -241,11 +238,14 @@ export function withVCR(...args) {
             options = args[0] || {};
             fn = args[1];
         }
+        if (!fn) {
+            throw new Error("VCR: No test function provided.");
+        }
         // Pass captured inherited scopes if not explicitly overridden
         if (capturedScopes.length > 0 && !options.scope) {
             options.scope = capturedScopes;
         }
-        if (!name && vitestExpect) {
+        if (!name && vitestExpect?.getState) {
             const state = vitestExpect.getState();
             name = state.currentTestName || "unnamed-test";
         }

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@node-llm/testing",
-  "version": "0.01.0",
+  "version": "0.2.1",
   "description": "Deterministic testing for NodeLLM powered AI systems",
   "main": "dist/index.js",
   "type": "module",
+  "dependencies": {},
+  "devDependencies": {
+    "vitest": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@node-llm/core": "1.8.0"
+  },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
     "test:record": "VCR_MODE=record vitest run",
     "test:vitest": "vitest run"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@node-llm/core": "workspace:*",
-    "vitest": "^1.0.0",
-    "typescript": "^5.0.0"
   }
-}
+}