@zudojs/testing 0.1.0 → 1.1.0

package/dist/assertions/index.js

@@ -1,9 +1,9 @@
 /**
- * Assertion helpers.
- *
- * HTTP, error, and event assertion utilities.
+ * @zudojs/testing — Assertions Barrel
  */
-export { assertResponseStatus, assertResponseHeader, assertResponseBody, assertOK, assertCreated, assertNoContent, assertBadRequest, assertNotFound, assertServerError, } from "./httpAssertions.core.js";
-export { assertThrows, assertRejects, assertErrorCode, assertErrorMetadata, } from "./errorAssertions.core.js";
-export { assertEventType, assertEventPayload, assertRecordedEventType, assertEventPublished, assertMessageDispatched, } from "./eventAssertions.core.js";
+export { assertBadRequest, assertCreated, assertNoContent, assertNotFound, assertOK, assertResponseBody, assertResponseBodyContains, assertResponseHeader, assertResponseStatus, assertServerError, } from "./httpAssertions.core.js";
+export { assertEventNotPublished, assertEventPayload, assertEventPublished, assertEventType, assertMessageDispatched, assertMessageNotDispatched, assertRecordedEventType, } from "./eventAssertions.core.js";
+export { assertErrorCode, assertErrorMetadata, assertErrorType, assertRejects, assertThrows, } from "./errorAssertions.core.js";
+export { deepEqual, findDifference } from "./deepEqual.core.js";
+export { describeValue } from "./deepEqual.describe.js";
 //# sourceMappingURL=index.js.map

package/dist/cleanupManager/cleanupManager.core.d.ts

@@ -28,6 +28,10 @@ export interface CleanupManagerOptions {
  * timers, database connections, and other resources leaking
  * after tests complete.
  *
+ * Every cleanup runs even if an earlier one fails, and `dispose()` then
+ * throws an `AggregateError` describing what failed. A leaked connection
+ * matters whether or not the other cleanups succeeded.
+ *
  * @example
  * ```ts
  * const cleanup = createCleanupManager();

package/dist/cleanupManager/cleanupManager.core.js

@@ -15,6 +15,7 @@ export function createCleanupManager(options = {}) {
     const entries = [];
     let nextId = 0;
     let disposed = false;
+    let inFlight;
     const register = (fn, label = `cleanup-${nextId}`) => {
         if (disposed) {
             throw new Error("Cannot register cleanup after manager has been disposed.");
@@ -25,11 +26,7 @@ export function createCleanupManager(options = {}) {
             fn,
         });
     };
-    const dispose = async () => {
-        if (disposed) {
-            return;
-        }
-        disposed = true;
+    const runCleanups = async () => {
         const errors = [];
         const reversed = [...entries].reverse();
         for (const entry of reversed) {
@@ -41,11 +38,31 @@ export function createCleanupManager(options = {}) {
                 options.onError?.(error, entry);
             }
         }
+        const attempted = reversed.length;
         entries.length = 0;
-        if (errors.length > 0 && errors.length === entries.length) {
-            throw new Error(`All ${errors.length} cleanup functions failed.`);
+        if (errors.length > 0) {
+            throw new AggregateError(errors.map((entry) => entry.error), `${errors.length} of ${attempted} cleanup functions failed: ${errors
+                .map((entry) => entry.entry.label)
+                .join(", ")}`);
         }
     };
+    /**
+     * Runs the cleanups once. A second call made while the first is still
+     * running shares its promise, so nobody is told "disposed" before the
+     * resources are actually released; a call after completion resolves
+     * immediately.
+     */
+    const dispose = () => {
+        if (inFlight)
+            return inFlight;
+        if (disposed)
+            return Promise.resolve();
+        disposed = true;
+        inFlight = runCleanups().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
     return {
         get disposed() {
             return disposed;

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

@@ -9,11 +9,20 @@
 export interface MockFn<TArgs extends readonly unknown[] = unknown[], TResult = unknown> {
     (...args: TArgs): TResult;
     readonly calls: readonly TArgs[];
+    /**
+     * Result of each call, aligned index-for-index with {@link calls}. A
+     * call whose implementation threw occupies its slot with `undefined`;
+     * the thrown value is in {@link errors}.
+     */
     readonly results: readonly TResult[];
+    /** Values thrown by the implementation, in call order. */
+    readonly errors: readonly unknown[];
     readonly invoked: boolean;
     readonly callCount: number;
     mockReturnValue: (value: TResult) => void;
-    mockResolvedValue: (value: TResult) => void;
+    /** Configures the mock to return a promise resolving to `value`. */
+    mockResolvedValue: (value: Awaited<TResult>) => void;
+    /** Configures the mock to return a promise rejecting with `error`. */
     mockRejectedValue: (error: unknown) => void;
     mockImplementation: (fn: (...args: TArgs) => TResult) => void;
     mockReset: () => void;

package/dist/mocking/mockFn.core.js

@@ -23,30 +23,47 @@
 export function createMockFn(defaultReturnValue) {
     const calls = [];
     const results = [];
-    let implementation;
-    let returnValue = defaultReturnValue;
-    let resolvedValue;
-    let rejectedValue;
-    let shouldReject = false;
+    const errors = [];
+    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;
+        let result;
+        try {
+            result = produce(args);
         }
-        if (implementation) {
-            const result = implementation(...args);
-            results.push(result);
-            return result;
+        catch (error) {
+            // Keep `results` aligned with `calls` even when the implementation
+            // throws; otherwise every later result shifts one index left.
+            results.push(undefined);
+            errors.push(error);
+            throw error;
         }
-        if (returnValue !== undefined) {
-            results.push(returnValue);
-            return returnValue;
-        }
-        return undefined;
+        results.push(result);
+        return result;
     });
     Object.defineProperty(mock, "calls", {
         get: () => calls,
@@ -56,6 +73,10 @@ export function createMockFn(defaultReturnValue) {
         get: () => results,
         enumerable: true,
     });
+    Object.defineProperty(mock, "errors", {
+        get: () => errors,
+        enumerable: true,
+    });
     Object.defineProperty(mock, "invoked", {
         get: () => calls.length > 0,
         enumerable: true,
@@ -65,39 +86,27 @@ 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;
+        errors.length = 0;
+        mode = initialMode;
     };
     mock.mockClear = () => {
         calls.length = 0;
         results.length = 0;
+        errors.length = 0;
     };
     return mock;
 }

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,27 @@
+/**
+ * @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.
+ *
+ * Uses the same walker as the assertions. The previous
+ * `JSON.stringify` comparison matched any two `Map`s or `Set`s (both
+ * render as `{}`), dropped `undefined` values, and treated key order as
+ * significant, so `findByMetadata` could both match what it should not
+ * and miss what it should find.
+ */
+export declare function deepMatches(actual: unknown, expected: unknown): boolean;
+//# sourceMappingURL=spyLogger.context.d.ts.map

package/dist/spyLogger/spyLogger.context.js

@@ -0,0 +1,44 @@
+/**
+ * @zudojs/testing — Logger context handling for the spy logger.
+ *
+ * @module spyLogger/spyLogger.context
+ */
+import { deepEqual } from "../assertions/deepEqual.core.js";
+/** 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.
+ *
+ * Uses the same walker as the assertions. The previous
+ * `JSON.stringify` comparison matched any two `Map`s or `Set`s (both
+ * render as `{}`), dropped `undefined` values, and treated key order as
+ * significant, so `findByMetadata` could both match what it should not
+ * and miss what it should find.
+ */
+export function deepMatches(actual, expected) {
+    return deepEqual(actual, 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;