@zudojs/testing 0.1.0 → 1.0.0

package/dist/mocking/mockFn.core.js

@@ -23,30 +23,36 @@
 export function createMockFn(defaultReturnValue) {
     const calls = [];
     const results = [];
-    let implementation;
-    let returnValue = defaultReturnValue;
-    let resolvedValue;
-    let rejectedValue;
-    let shouldReject = false;
+    const initialMode = arguments.length > 0
+        ? { kind: "value", value: defaultReturnValue }
+        : { kind: "none" };
+    let mode = initialMode;
+    /**
+     * Produce the configured result.
+     *
+     * `undefined` is a legitimate configured value, so the mode is tracked
+     * explicitly rather than inferred from a `!== undefined` check — which
+     * silently ignored `mockReturnValue(undefined)`.
+     */
+    const produce = (args) => {
+        switch (mode.kind) {
+            case "value":
+                return mode.value;
+            case "resolve":
+                return Promise.resolve(mode.value);
+            case "reject":
+                return Promise.reject(mode.error);
+            case "implementation":
+                return mode.fn(...args);
+            case "none":
+                return undefined;
+        }
+    };
     const mock = ((...args) => {
         calls.push(args);
-        if (shouldReject) {
-            throw rejectedValue;
-        }
-        if (resolvedValue !== undefined) {
-            results.push(resolvedValue);
-            return resolvedValue;
-        }
-        if (implementation) {
-            const result = implementation(...args);
-            results.push(result);
-            return result;
-        }
-        if (returnValue !== undefined) {
-            results.push(returnValue);
-            return returnValue;
-        }
-        return undefined;
+        const result = produce(args);
+        results.push(result);
+        return result;
     });
     Object.defineProperty(mock, "calls", {
         get: () => calls,
@@ -65,35 +71,21 @@ export function createMockFn(defaultReturnValue) {
         enumerable: true,
     });
     mock.mockReturnValue = (value) => {
-        returnValue = value;
-        resolvedValue = undefined;
-        shouldReject = false;
+        mode = { kind: "value", value };
     };
     mock.mockResolvedValue = (value) => {
-        resolvedValue = value;
-        returnValue = undefined;
-        shouldReject = false;
+        mode = { kind: "resolve", value };
     };
     mock.mockRejectedValue = (error) => {
-        rejectedValue = error;
-        shouldReject = true;
-        returnValue = undefined;
-        resolvedValue = undefined;
+        mode = { kind: "reject", error };
     };
     mock.mockImplementation = (fn) => {
-        implementation = fn;
-        returnValue = undefined;
-        resolvedValue = undefined;
-        shouldReject = false;
+        mode = { kind: "implementation", fn: fn };
     };
     mock.mockReset = () => {
         calls.length = 0;
         results.length = 0;
-        implementation = undefined;
-        returnValue = defaultReturnValue;
-        resolvedValue = undefined;
-        rejectedValue = undefined;
-        shouldReject = false;
+        mode = initialMode;
     };
     mock.mockClear = () => {
         calls.length = 0;

package/dist/mocking/spy.core.d.ts

@@ -11,12 +11,18 @@ export interface SpyFn<TArgs extends readonly unknown[] = unknown[], TResult = u
     readonly original: (...args: TArgs) => TResult;
     readonly calls: readonly TArgs[];
     readonly results: readonly TResult[];
+    /** Errors thrown by the wrapped function, in call order. */
+    readonly errors: readonly unknown[];
     readonly callCount: number;
-    restore: () => void;
+    /** Clears the recorded calls, results and errors. */
+    reset: () => void;
 }
 /**
  * Creates a spy that wraps an existing function.
  *
+ * The wrapper forwards its receiver, so a spy taken on a method still works
+ * when the method reads instance state.
+ *
  * @param fn - The function to spy on.
  * @returns A SpyFn instance.
  *
@@ -29,7 +35,7 @@ export interface SpyFn<TArgs extends readonly unknown[] = unknown[], TResult = u
  * expect(spy.calls).toHaveLength(1);
  * expect(spy.calls[0]).toEqual([1, 2]);
  *
- * spy.restore();
+ * spy.reset();
  * ```
  */
 export declare function createSpyFn<TArgs extends readonly unknown[] = unknown[], TResult = unknown>(fn: (...args: TArgs) => TResult): SpyFn<TArgs, TResult>;
@@ -40,7 +46,10 @@ export interface SpyMethod<TObj, TMethod extends keyof TObj> {
     readonly object: TObj;
     readonly property: TMethod;
     readonly calls: readonly unknown[][];
+    readonly results: readonly unknown[];
+    readonly errors: readonly unknown[];
     readonly callCount: number;
+    /** Reinstates the original method exactly as it was found. */
     restore: () => void;
 }
 /**

package/dist/mocking/spy.core.js

@@ -6,6 +6,9 @@
 /**
  * Creates a spy that wraps an existing function.
  *
+ * The wrapper forwards its receiver, so a spy taken on a method still works
+ * when the method reads instance state.
+ *
  * @param fn - The function to spy on.
  * @returns A SpyFn instance.
  *
@@ -18,38 +21,42 @@
  * expect(spy.calls).toHaveLength(1);
  * expect(spy.calls[0]).toEqual([1, 2]);
  *
- * spy.restore();
+ * spy.reset();
  * ```
  */
 export function createSpyFn(fn) {
     const calls = [];
     const results = [];
-    const spy = ((...args) => {
+    const errors = [];
+    const spy = function (...args) {
         calls.push(args);
-        const result = fn(...args);
-        results.push(result);
-        return result;
-    });
+        try {
+            const result = Reflect.apply(fn, this, args);
+            results.push(result);
+            return result;
+        }
+        catch (error) {
+            errors.push(error);
+            throw error;
+        }
+    };
     Object.defineProperty(spy, "original", {
         value: fn,
         writable: false,
         enumerable: true,
     });
-    Object.defineProperty(spy, "calls", {
-        get: () => calls,
-        enumerable: true,
-    });
-    Object.defineProperty(spy, "results", {
-        get: () => results,
-        enumerable: true,
-    });
-    Object.defineProperty(spy, "callCount", {
-        get: () => calls.length,
-        enumerable: true,
-    });
-    spy.restore = () => {
+    for (const [name, get] of [
+        ["calls", () => calls],
+        ["results", () => results],
+        ["errors", () => errors],
+        ["callCount", () => calls.length],
+    ]) {
+        Object.defineProperty(spy, name, { get, enumerable: true });
+    }
+    spy.reset = () => {
         calls.length = 0;
         results.length = 0;
+        errors.length = 0;
     };
     return spy;
 }
@@ -74,26 +81,48 @@ export function createSpyFn(fn) {
  */
 export function createSpyMethod(object, property) {
     const original = object[property];
-    const calls = [];
     if (typeof original !== "function") {
         throw new TypeError(`Property "${String(property)}" is not a function.`);
     }
+    const key = property;
+    const target = object;
+    // Whether the method was the object's own or inherited from a prototype.
+    // Reassigning an inherited method and then "restoring" it by assignment
+    // leaves a permanent own property that changes enumeration and hasOwn.
+    const wasOwnProperty = Object.hasOwn(target, key);
     const originalFn = original;
-    object[property] = ((...args) => {
+    const calls = [];
+    const results = [];
+    const errors = [];
+    target[key] = function (...args) {
         calls.push(args);
-        return originalFn(...args);
-    });
+        try {
+            const result = originalFn.apply(this ?? object, args);
+            results.push(result);
+            return result;
+        }
+        catch (error) {
+            errors.push(error);
+            throw error;
+        }
+    };
     return {
         object,
         property,
         calls,
+        results,
+        errors,
         get callCount() {
             return calls.length;
         },
         restore: () => {
-            object[property] =
-                original;
+            if (wasOwnProperty)
+                target[key] = original;
+            else
+                delete target[key];
             calls.length = 0;
+            results.length = 0;
+            errors.length = 0;
         },
     };
 }

package/dist/mocking/stub.core.d.ts

@@ -25,32 +25,35 @@
  * });
  *
  * expect(await stub.find("123")).toEqual({ id: "123", name: "Test" });
- * expect(stub.create).toBeUndefined();
  * ```
  */
-export declare function createStub<T extends Record<string, unknown>>(overrides?: Partial<T>): T;
+export declare function createStub<T extends object>(overrides?: Partial<T>): T;
 /**
  * Creates a stub class constructor.
  *
+ * Instances keep the original prototype, so `instanceof` holds and methods
+ * that were not overridden exist as no-ops rather than being absent.
+ *
  * @typeParam T - The class type to stub.
+ * @param OriginalClass - The class being stubbed.
  * @param overrides - Optional property and method implementations.
  * @returns A stub class constructor.
  *
  * @example
  * ```ts
  * class RealDatabase {
- *   async connect(): Promise<void> { /* real implementation *\/ }
- *   async query(sql: string): Promise<unknown[]> { /* real implementation *\/ }
+ *   async connect(): Promise<void> {}
+ *   async query(sql: string): Promise<unknown[]> { return []; }
  * }
  *
  * const StubDatabase = createStubClass(RealDatabase, {
- *   connect: async () => {},
  *   query: async () => [],
  * });
  *
  * const db = new StubDatabase();
+ * expect(db).toBeInstanceOf(RealDatabase);
  * await db.connect();
  * ```
  */
-export declare function createStubClass<T>(_OriginalClass: new (...args: unknown[]) => T, overrides?: Partial<T>): new () => T;
+export declare function createStubClass<T extends object>(OriginalClass: new (...args: never[]) => T, overrides?: Partial<T>): new () => T;
 //# sourceMappingURL=stub.core.d.ts.map

package/dist/mocking/stub.core.js

@@ -3,6 +3,22 @@
  *
  * Creates fake implementations of interfaces for testing.
  */
+/**
+ * Properties a stub must never answer with a function.
+ *
+ * `then` is the important one: answering it makes the stub a thenable, so
+ * `await stub` calls it expecting a promise callback. The fake never resolves,
+ * and the test hangs until it times out with no indication why.
+ */
+const NON_CALLABLE_KEYS = new Set([
+    "then",
+    "catch",
+    "finally",
+    Symbol.toPrimitive,
+    Symbol.iterator,
+    Symbol.asyncIterator,
+    Symbol.toStringTag,
+]);
 /**
  * Creates a stub object from an interface.
  *
@@ -25,53 +41,74 @@
  * });
  *
  * expect(await stub.find("123")).toEqual({ id: "123", name: "Test" });
- * expect(stub.create).toBeUndefined();
  * ```
  */
 export function createStub(overrides = {}) {
     return new Proxy({}, {
         get(_target, prop, _receiver) {
-            const key = prop;
-            if (key in overrides) {
-                return overrides[key];
+            // `hasOwn`, not `in`: `in` walks the prototype chain, so `toString`,
+            // `constructor` and `valueOf` resolved to undefined instead of stubs.
+            if (Object.hasOwn(overrides, prop)) {
+                return overrides[prop];
             }
-            if (typeof prop === "symbol") {
+            if (NON_CALLABLE_KEYS.has(prop))
+                return undefined;
+            if (typeof prop === "symbol")
                 return undefined;
-            }
             return (..._args) => undefined;
         },
+        has(_target, prop) {
+            return !NON_CALLABLE_KEYS.has(prop);
+        },
     });
 }
 /**
  * Creates a stub class constructor.
  *
+ * Instances keep the original prototype, so `instanceof` holds and methods
+ * that were not overridden exist as no-ops rather than being absent.
+ *
  * @typeParam T - The class type to stub.
+ * @param OriginalClass - The class being stubbed.
  * @param overrides - Optional property and method implementations.
  * @returns A stub class constructor.
  *
  * @example
  * ```ts
  * class RealDatabase {
- *   async connect(): Promise<void> { /* real implementation *\/ }
- *   async query(sql: string): Promise<unknown[]> { /* real implementation *\/ }
+ *   async connect(): Promise<void> {}
+ *   async query(sql: string): Promise<unknown[]> { return []; }
  * }
  *
  * const StubDatabase = createStubClass(RealDatabase, {
- *   connect: async () => {},
  *   query: async () => [],
  * });
  *
  * const db = new StubDatabase();
+ * expect(db).toBeInstanceOf(RealDatabase);
  * await db.connect();
  * ```
  */
-export function createStubClass(_OriginalClass, overrides = {}) {
-    return class {
+export function createStubClass(OriginalClass, overrides = {}) {
+    const prototype = OriginalClass.prototype;
+    const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => {
+        if (name === "constructor")
+            return false;
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+        return typeof descriptor?.value === "function";
+    });
+    class Stub {
         constructor() {
+            for (const name of methodNames) {
+                this[name] = () => undefined;
+            }
             for (const [key, value] of Object.entries(overrides)) {
                 this[key] = value;
             }
         }
-    };
+    }
+    Object.setPrototypeOf(Stub.prototype, prototype);
+    Object.setPrototypeOf(Stub, OriginalClass);
+    return Stub;
 }
 //# sourceMappingURL=stub.core.js.map

package/dist/spyLogger/index.d.ts

@@ -1,8 +1,9 @@
 /**
- * @zudojs/testing — Spy logger for testing.
- *
- * Records all log calls for assertion.
+ * @zudojs/testing — Spy Logger Barrel
  */
 export { createSpyLogger } from "./spyLogger.core.js";
-export type { LogCall, SpyLogger } from "./spyLogger.type.js";
+export { LEVELS, createRecordingLogger } from "./spyLogger.recording.js";
+export type { DerivedOptions, Recorder } from "./spyLogger.recording.js";
+export { deepMatches, mergeContext, mergeLoggerContext, } from "./spyLogger.context.js";
+export type * from "./spyLogger.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/spyLogger/index.js

@@ -1,7 +1,7 @@
 /**
- * @zudojs/testing — Spy logger for testing.
- *
- * Records all log calls for assertion.
+ * @zudojs/testing — Spy Logger Barrel
  */
 export { createSpyLogger } from "./spyLogger.core.js";
+export { LEVELS, createRecordingLogger } from "./spyLogger.recording.js";
+export { deepMatches, mergeContext, mergeLoggerContext, } from "./spyLogger.context.js";
 //# sourceMappingURL=index.js.map

package/dist/spyLogger/spyLogger.context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @zudojs/testing — Logger context handling for the spy logger.
+ *
+ * @module spyLogger/spyLogger.context
+ */
+import type { LogMetadata, LoggerContext } from "@zudojs/logger";
+/** Merges two logger contexts, preserving the nested shape. */
+export declare function mergeLoggerContext(base: LoggerContext | undefined, next: LoggerContext): LoggerContext;
+/**
+ * Flattens a logger context onto a call's metadata.
+ *
+ * `LoggerContext` nests identifiers and metadata, so it is flattened rather
+ * than spread wholesale: a test asserting on `tenantId` should find it at the
+ * top level, the way a real transport would render it.
+ */
+export declare function mergeContext(context: LoggerContext | undefined, metadata: LogMetadata | undefined): LogMetadata | undefined;
+/** Structural comparison, so object metadata can actually be matched. */
+export declare function deepMatches(actual: unknown, expected: unknown): boolean;
+//# sourceMappingURL=spyLogger.context.d.ts.map

package/dist/spyLogger/spyLogger.context.js

@@ -0,0 +1,41 @@
+/**
+ * @zudojs/testing — Logger context handling for the spy logger.
+ *
+ * @module spyLogger/spyLogger.context
+ */
+/** Merges two logger contexts, preserving the nested shape. */
+export function mergeLoggerContext(base, next) {
+    if (!base)
+        return next;
+    return {
+        identifiers: { ...base.identifiers, ...next.identifiers },
+        metadata: { ...base.metadata, ...next.metadata },
+    };
+}
+/**
+ * Flattens a logger context onto a call's metadata.
+ *
+ * `LoggerContext` nests identifiers and metadata, so it is flattened rather
+ * than spread wholesale: a test asserting on `tenantId` should find it at the
+ * top level, the way a real transport would render it.
+ */
+export function mergeContext(context, metadata) {
+    if (!context)
+        return metadata;
+    return {
+        ...context.identifiers,
+        ...context.metadata,
+        ...metadata,
+    };
+}
+/** Structural comparison, so object metadata can actually be matched. */
+export function deepMatches(actual, expected) {
+    if (Object.is(actual, expected))
+        return true;
+    if (typeof actual !== "object" || typeof expected !== "object")
+        return false;
+    if (actual === null || expected === null)
+        return false;
+    return JSON.stringify(actual) === JSON.stringify(expected);
+}
+//# sourceMappingURL=spyLogger.context.js.map

package/dist/spyLogger/spyLogger.core.d.ts

@@ -8,8 +8,14 @@ import type { SpyLogger } from "./spyLogger.type.js";
 /**
  * Creates a spy logger that records all log calls.
  *
+ * A logger derived with `child()` or `withContext()` writes into the *same*
+ * recording as its parent, the way a real logger shares a transport. Giving
+ * the derived logger its own array meant code under test that called
+ * `logger.child({ module })` — the normal pattern — logged into an array
+ * nobody held, so assertions on the parent silently saw nothing.
+ *
  * @param name - Logger name.
- * @param level - Optional minimum level (defaults to TRACE = all).
+ * @param level - Minimum level recorded. Defaults to TRACE (everything).
  * @returns A SpyLogger instance.
  */
 export declare function createSpyLogger(name?: string, level?: LoggerLevel): SpyLogger;

package/dist/spyLogger/spyLogger.core.js

@@ -3,67 +3,21 @@
  *
  * Records all log calls for assertion without side effects.
  */
-function recordCall(calls, method, level, message, metadata) {
-    calls.push({ method, level, message, metadata, timestamp: new Date() });
-}
+import { LEVELS, createRecordingLogger } from "./spyLogger.recording.js";
 /**
  * Creates a spy logger that records all log calls.
  *
+ * A logger derived with `child()` or `withContext()` writes into the *same*
+ * recording as its parent, the way a real logger shares a transport. Giving
+ * the derived logger its own array meant code under test that called
+ * `logger.child({ module })` — the normal pattern — logged into an array
+ * nobody held, so assertions on the parent silently saw nothing.
+ *
  * @param name - Logger name.
- * @param level - Optional minimum level (defaults to TRACE = all).
+ * @param level - Minimum level recorded. Defaults to TRACE (everything).
  * @returns A SpyLogger instance.
  */
-export function createSpyLogger(name = "test", level = 5) {
-    const calls = [];
-    return {
-        get name() {
-            return name;
-        },
-        get level() {
-            return level;
-        },
-        get enabled() {
-            return true;
-        },
-        get calls() {
-            return calls;
-        },
-        fatal: (message, metadata) => {
-            recordCall(calls, "fatal", 0, message, metadata);
-        },
-        error: (message, metadata) => {
-            recordCall(calls, "error", 1, message, metadata);
-        },
-        warn: (message, metadata) => {
-            recordCall(calls, "warn", 2, message, metadata);
-        },
-        info: (message, metadata) => {
-            recordCall(calls, "info", 3, message, metadata);
-        },
-        debug: (message, metadata) => {
-            recordCall(calls, "debug", 4, message, metadata);
-        },
-        trace: (message, metadata) => {
-            recordCall(calls, "trace", 5, message, metadata);
-        },
-        log: (logLevel, message, options) => {
-            recordCall(calls, "log", logLevel, message, options?.metadata);
-        },
-        child: (_options) => createSpyLogger(`${name}.child`, level),
-        withContext: (_context) => createSpyLogger(name, level),
-        setLevel: (newLevel) => {
-            level = newLevel;
-        },
-        enable: () => { },
-        disable: () => { },
-        flush: async () => { },
-        close: async () => { },
-        clear: () => {
-            calls.length = 0;
-        },
-        findByMethod: (method) => calls.filter((c) => c.method === method),
-        findByMessage: (substring) => calls.filter((c) => c.message.includes(substring)),
-        findByMetadata: (key, value) => calls.filter((c) => c.metadata !== undefined && c.metadata[key] === value),
-    };
+export function createSpyLogger(name = "test", level = LEVELS.trace) {
+    return createRecordingLogger({ calls: [] }, { name }, level, true);
 }
 //# sourceMappingURL=spyLogger.core.js.map

package/dist/spyLogger/spyLogger.recording.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/testing — Recording logger construction.
+ *
+ * Split from the factory so a derived logger — `child()` or `withContext()` —
+ * is built the same way as its parent and shares the same recording.
+ *
+ * @module spyLogger/spyLogger.recording
+ */
+import type { LoggerLevel, LoggerContext } from "@zudojs/logger";
+import type { LogCall, SpyLogger } from "./spyLogger.type.js";
+/** Numeric level for each method, ascending in verbosity. */
+export declare const LEVELS: {
+    readonly fatal: 0;
+    readonly error: 1;
+    readonly warn: 2;
+    readonly info: 3;
+    readonly debug: 4;
+    readonly trace: 5;
+};
+/** Shared recording state, so derived loggers report to their parent. */
+export interface Recorder {
+    readonly calls: LogCall[];
+}
+/** Options controlling a derived logger's identity. */
+export interface DerivedOptions {
+    readonly name: string;
+    readonly context?: LoggerContext;
+}
+/** Builds a logger over an existing recording. */
+export declare function createRecordingLogger(recorder: Recorder, derived: DerivedOptions, initialLevel: LoggerLevel, initiallyEnabled: boolean): SpyLogger;
+//# sourceMappingURL=spyLogger.recording.d.ts.map