1tube 0.2.0 → 0.4.0

package/dist/test/core.js

@@ -0,0 +1,100 @@
+/**
+ * Builds the full `1tube/test` surface from a runner's minimal base, so
+ * `.each`, `.if`/`.skipIf`, `it`, mocks and title formatting behave the
+ * same on every runner.
+ */
+import { format } from "./assert.js";
+import { createMock, restoreAllMocks } from "./expect.js";
+const rowArgs = (row) => (Array.isArray(row) ? row : [row]);
+/** jest-style `.each` titles: printf placeholders, or `$path` for object rows. */
+export function formatTitle(title, args, index) {
+    const [first] = args;
+    if (args.length === 1 && first && typeof first === "object" && !Array.isArray(first) && /\$[A-Za-z_]/.test(title)) {
+        return title.replace(/\$([A-Za-z_$][\w$]*(?:\.[\w$]+)*)/g, (m, path) => {
+            let cur = first;
+            for (const p of path.split(".")) {
+                if (cur === null || cur === undefined)
+                    return m;
+                cur = cur[p];
+            }
+            return typeof cur === "string" ? cur : format(cur);
+        });
+    }
+    let i = 0;
+    return title.replace(/%[sdifjoOp#%]/g, (m) => {
+        if (m === "%%")
+            return "%";
+        if (m === "%#")
+            return String(index);
+        if (i >= args.length)
+            return m;
+        const v = args[i++];
+        switch (m) {
+            case "%s":
+                return typeof v === "string" ? v : format(v);
+            case "%d":
+            case "%i":
+                return String(typeof v === "bigint" ? v : Math.trunc(Number(v)));
+            case "%f":
+                return String(Number(v));
+            case "%j":
+                return JSON.stringify(v);
+            default:
+                return format(v);
+        }
+    });
+}
+export function createTestApi(base) {
+    const register = (mode) => (name, fn, options = {}) => base.test(name, fn, {
+        ...options,
+        skip: mode === "skip" || options.skip,
+        only: mode === "only" || options.only,
+    });
+    const test = Object.assign(register("run"), {
+        skip: register("skip"),
+        only: register("only"),
+        todo: (name) => base.todo(name),
+        if: (condition) => register(condition ? "run" : "skip"),
+        skipIf: (condition) => register(condition ? "skip" : "run"),
+        each: (table) => (name, fn, options) => {
+            table.forEach((row, index) => {
+                const args = rowArgs(row);
+                register("run")(formatTitle(name, args, index), (() => fn(...args)), options);
+            });
+        },
+    });
+    const suite = (mode) => (name, fn) => base.describe(name, fn, mode);
+    const describe = Object.assign(suite("run"), {
+        skip: suite("skip"),
+        only: suite("only"),
+        if: (condition) => suite(condition ? "run" : "skip"),
+        skipIf: (condition) => suite(condition ? "skip" : "run"),
+        each: (table) => (name, fn) => {
+            table.forEach((row, index) => {
+                const args = rowArgs(row);
+                suite("run")(formatTitle(name, args, index), () => fn(...args));
+            });
+        },
+    });
+    const mock = Object.assign((impl) => createMock(impl), {
+        module: (specifier, factory) => {
+            const s = specifier instanceof URL ? specifier.href : String(specifier);
+            if (s.startsWith("./") || s.startsWith("../") || s === "." || s === "..") {
+                throw new Error(`mock.module(${JSON.stringify(s)}): relative specifiers depend on the calling file, which a ` +
+                    `shared helper can't see. Pass import.meta.resolve(${JSON.stringify(s)}) instead.`);
+            }
+            base.mockModule(s, factory);
+        },
+        restore: () => restoreAllMocks(),
+    });
+    return {
+        test,
+        it: test,
+        describe,
+        beforeAll: base.beforeAll,
+        afterAll: base.afterAll,
+        beforeEach: base.beforeEach,
+        afterEach: base.afterEach,
+        mock,
+    };
+}

package/dist/test/expect.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Runtime-agnostic `expect`, mock functions and spies for `1tube/test`.
+ *
+ * Pure TypeScript with no runtime imports — the same semantics under every
+ * runner. Matchers follow the jest conventions Bun's `bun:test` also uses
+ * (`toEqual` ignores `undefined` properties and object types,
+ * `toStrictEqual` does not, `toMatchObject` matches subsets, asymmetric
+ * matchers like `expect.objectContaining` nest anywhere), so tests written
+ * against `bun:test` port by changing the import line.
+ */
+declare const ASYMMETRIC: unique symbol;
+export interface AsymmetricMatcher {
+    readonly [ASYMMETRIC]: true;
+    asymmetricMatch(other: unknown): boolean;
+    toString(): string;
+}
+/**
+ * jest-style deep equality. `strict` (toStrictEqual) additionally checks
+ * constructors, `undefined`-valued keys and array holes.
+ */
+export declare function deepEquals(a: unknown, b: unknown, strict?: boolean): boolean;
+type AnyFn = (...args: any[]) => any;
+export type MockResult<T> = {
+    type: "return";
+    value: T;
+} | {
+    type: "throw";
+    value: unknown;
+} | {
+    type: "incomplete";
+    value: undefined;
+};
+export interface MockState<T extends AnyFn> {
+    calls: Parameters<T>[];
+    results: MockResult<ReturnType<T>>[];
+    instances: unknown[];
+    lastCall: Parameters<T> | undefined;
+}
+export type Mock<T extends AnyFn = AnyFn> = T & {
+    readonly mock: MockState<T>;
+    mockImplementation(fn: T): Mock<T>;
+    mockImplementationOnce(fn: T): Mock<T>;
+    mockReturnValue(value: ReturnType<T>): Mock<T>;
+    mockReturnValueOnce(value: ReturnType<T>): Mock<T>;
+    mockResolvedValue(value: Awaited<ReturnType<T>>): Mock<T>;
+    mockResolvedValueOnce(value: Awaited<ReturnType<T>>): Mock<T>;
+    mockRejectedValue(value: unknown): Mock<T>;
+    mockRejectedValueOnce(value: unknown): Mock<T>;
+    mockName(name: string): Mock<T>;
+    getMockName(): string;
+    /** Forget recorded calls and results. */
+    mockClear(): Mock<T>;
+    /** mockClear() plus drop implementations. */
+    mockReset(): Mock<T>;
+    /** For spies: put the original method back. */
+    mockRestore(): void;
+};
+/** Create a mock function, optionally wrapping an implementation. */
+export declare function createMock<T extends AnyFn = AnyFn>(impl?: T, restore?: () => void): Mock<T>;
+export declare function isMock(v: unknown): v is Mock;
+/** Replace `obj[key]` with a mock that calls through to the original. */
+export declare function spyOn<O extends object, K extends keyof O>(obj: O, key: K): O[K] extends AnyFn ? Mock<O[K]> : never;
+/** Restore every active spy (`mock.restore()`). */
+export declare function restoreAllMocks(): void;
+export interface Matchers<R> {
+    not: Matchers<R>;
+    toBe(expected: unknown): R;
+    toEqual(expected: unknown): R;
+    toStrictEqual(expected: unknown): R;
+    toMatchObject(expected: object): R;
+    toBeNull(): R;
+    toBeUndefined(): R;
+    toBeDefined(): R;
+    toBeTruthy(): R;
+    toBeFalsy(): R;
+    toBeNaN(): R;
+    toBeTypeOf(type: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function"): R;
+    toBeInstanceOf(ctor: abstract new (...args: never[]) => unknown): R;
+    toBeGreaterThan(n: number | bigint): R;
+    toBeGreaterThanOrEqual(n: number | bigint): R;
+    toBeLessThan(n: number | bigint): R;
+    toBeLessThanOrEqual(n: number | bigint): R;
+    toBeCloseTo(n: number, numDigits?: number): R;
+    toBeOneOf(values: readonly unknown[]): R;
+    toContain(item: unknown): R;
+    toContainEqual(item: unknown): R;
+    toInclude(substring: string): R;
+    toStartWith(prefix: string): R;
+    toEndWith(suffix: string): R;
+    toMatch(pattern: string | RegExp): R;
+    toHaveLength(n: number): R;
+    toHaveProperty(path: string | readonly (string | number)[], value?: unknown): R;
+    toBeEmpty(): R;
+    toThrow(expected?: string | RegExp | Error | (abstract new (...args: never[]) => unknown) | AsymmetricMatcher): R;
+    toThrowError(expected?: string | RegExp | Error | (abstract new (...args: never[]) => unknown) | AsymmetricMatcher): R;
+    toHaveBeenCalled(): R;
+    toHaveBeenCalledTimes(n: number): R;
+    toHaveBeenCalledWith(...args: unknown[]): R;
+    toHaveBeenLastCalledWith(...args: unknown[]): R;
+    toHaveBeenNthCalledWith(n: number, ...args: unknown[]): R;
+    toHaveReturned(): R;
+    toHaveReturnedTimes(n: number): R;
+    toHaveReturnedWith(value: unknown): R;
+}
+export interface Assertion extends Matchers<void> {
+    /** Await the promise, then match its value. */
+    resolves: Matchers<Promise<void>>;
+    /** Await the promise, then match its rejection reason. */
+    rejects: Matchers<Promise<void>>;
+}
+export interface Expect {
+    (actual: unknown, message?: string): Assertion;
+    anything(): AsymmetricMatcher;
+    any(ctor: unknown): AsymmetricMatcher;
+    objectContaining(obj: object): AsymmetricMatcher;
+    arrayContaining(items: readonly unknown[]): AsymmetricMatcher;
+    stringContaining(s: string): AsymmetricMatcher;
+    stringMatching(p: string | RegExp): AsymmetricMatcher;
+    closeTo(n: number, numDigits?: number): AsymmetricMatcher;
+    not: {
+        objectContaining(obj: object): AsymmetricMatcher;
+        arrayContaining(items: readonly unknown[]): AsymmetricMatcher;
+        stringContaining(s: string): AsymmetricMatcher;
+        stringMatching(p: string | RegExp): AsymmetricMatcher;
+    };
+}
+export declare const expect: Expect;
+export {};