1tube 0.3.0 → 0.5.0

package/dist/test/api.d.ts

@@ -1,12 +1,13 @@
 /**
  * The `1tube/test` contract every runner binding implements.
  *
- * Edge function tests import `test`, `describe`, hooks and assertions from
- * `1tube/test` instead of a specific runner, so the same files run under
- * `bun test` today and under another runtime's runner (node:test, a workerd
- * pool) later. Keep this surface to what every runner can express: no test
- * context argument, no runner-specific options.
+ * Edge function tests import `test`, `describe`, hooks, `expect`, mocks and
+ * assertions from `1tube/test` instead of a specific runner, so the same
+ * files run under `bun test` today and under another runtime's runner
+ * (node:test, a workerd pool) later. Keep this surface to what every runner
+ * can express: no test context argument, no runner-specific options.
  */
+import type { Mock } from "./expect.ts";
 export type TestFn = () => void | Promise<unknown>;
 export type HookFn = () => void | Promise<unknown>;
 export interface TestOptions {
@@ -17,18 +18,59 @@ export interface TestOptions {
     /** Run only tests marked `only` (where the runner supports focusing). */
     only?: boolean;
 }
-export interface TestFunction {
-    (name: string, fn: TestFn, options?: TestOptions): void;
-    skip(name: string, fn: TestFn, options?: TestOptions): void;
-    only(name: string, fn: TestFn, options?: TestOptions): void;
+/** Row arguments for `.each`: array rows spread, anything else is one argument. */
+export type EachArgs<Row> = Row extends readonly unknown[] ? Row : [Row];
+export type RegisterTest = (name: string, fn: TestFn, options?: TestOptions) => void;
+export interface TestFunction extends RegisterTest {
+    skip: RegisterTest;
+    only: RegisterTest;
     /** A placeholder for a test that is not written yet. */
     todo(name: string): void;
+    /** Register normally when `condition` is truthy, else as skipped. */
+    if(condition: unknown): RegisterTest;
+    /** Register as skipped when `condition` is truthy. */
+    skipIf(condition: unknown): RegisterTest;
+    /**
+     * One test per row. The name supports printf placeholders (`%s %d %i %f
+     * %j %o %p %#`) and `$key` for object rows.
+     */
+    each<Row>(table: readonly Row[]): (name: string, fn: (...args: EachArgs<Row>) => void | Promise<unknown>, options?: TestOptions) => void;
 }
-export interface DescribeFunction {
-    (name: string, fn: () => void): void;
-    skip(name: string, fn: () => void): void;
-    only(name: string, fn: () => void): void;
+export type RegisterSuite = (name: string, fn: () => void) => void;
+export interface DescribeFunction extends RegisterSuite {
+    skip: RegisterSuite;
+    only: RegisterSuite;
+    if(condition: unknown): RegisterSuite;
+    skipIf(condition: unknown): RegisterSuite;
+    each<Row>(table: readonly Row[]): (name: string, fn: (...args: EachArgs<Row>) => void) => void;
 }
 export type Hook = (fn: HookFn) => void;
+type AnyFn = (...args: any[]) => any;
+export interface MockFunction {
+    /** A mock function (records calls; optional implementation). */
+    <T extends AnyFn = AnyFn>(impl?: T): Mock<T>;
+    /**
+     * Replace a module for subsequently loaded importers. The specifier must
+     * be absolute — a shared helper can't know which file called it — so
+     * pass `import.meta.resolve("./dep.ts")` or a package name. The factory
+     * returns the module's exports (`default` for the default export).
+     */
+    module(specifier: string | URL, factory: () => Record<string, unknown>): void;
+    /** Restore every `spyOn` replacement. */
+    restore(): void;
+}
 /** Which runner the active binding drives. */
 export type TestRuntime = "bun" | "node";
+/** What a runner binding provides; `createTestApi` builds the rest. */
+export interface RunnerBase {
+    test(name: string, fn: TestFn, options: TestOptions): void;
+    todo(name: string): void;
+    describe(name: string, fn: () => void, mode: "run" | "skip" | "only"): void;
+    beforeAll: Hook;
+    afterAll: Hook;
+    beforeEach: Hook;
+    afterEach: Hook;
+    /** `specifier` is already checked to be absolute (path, file: URL or bare). */
+    mockModule(specifier: string, factory: () => Record<string, unknown>): void;
+}
+export {};

package/dist/test/api.js

@@ -1,10 +1,10 @@
 /**
  * The `1tube/test` contract every runner binding implements.
  *
- * Edge function tests import `test`, `describe`, hooks and assertions from
- * `1tube/test` instead of a specific runner, so the same files run under
- * `bun test` today and under another runtime's runner (node:test, a workerd
- * pool) later. Keep this surface to what every runner can express: no test
- * context argument, no runner-specific options.
+ * Edge function tests import `test`, `describe`, hooks, `expect`, mocks and
+ * assertions from `1tube/test` instead of a specific runner, so the same
+ * files run under `bun test` today and under another runtime's runner
+ * (node:test, a workerd pool) later. Keep this surface to what every runner
+ * can express: no test context argument, no runner-specific options.
  */
 export {};

package/dist/test/assert.d.ts

@@ -15,6 +15,8 @@ type AnyConstructor = abstract new (...args: never[]) => unknown;
 type ErrorClass<E extends Error = Error> = abstract new (...args: never[]) => E;
 /** Readable, deterministic rendering of a value for failure messages. */
 export declare function format(value: unknown): string;
+/** Line-level diff of two formatted values (`-` actual, `+` expected). */
+export declare function formatDiff(actual: unknown, expected: unknown): string;
 /**
  * Deep structural equality: same constructor, same own enumerable keys
  * (strings and symbols), recursively equal values. `NaN` equals `NaN`;

package/dist/test/assert.js

@@ -99,7 +99,7 @@ export function format(value) {
     return render(value);
 }
 /** Line-level diff of two formatted values (`-` actual, `+` expected). */
-function diff(actual, expected) {
+export function formatDiff(actual, expected) {
     const a = format(actual).split("\n");
     const b = format(expected).split("\n");
     // LCS over lines: values printed for assertion failures are small.
@@ -245,7 +245,7 @@ export function assertFalse(expr, msg = "") {
 export function assertEquals(actual, expected, msg) {
     if (equal(actual, expected))
         return;
-    throw new AssertionError(`Values are not equal${suffix(msg)}\n\n    [Diff] Actual / Expected\n\n${diff(actual, expected)}\n`);
+    throw new AssertionError(`Values are not equal${suffix(msg)}\n\n    [Diff] Actual / Expected\n\n${formatDiff(actual, expected)}\n`);
 }
 export function assertNotEquals(actual, expected, msg) {
     if (!equal(actual, expected))
@@ -259,7 +259,7 @@ export function assertStrictEquals(actual, expected, msg) {
     const sameRendering = format(actual) === format(expected);
     throw new AssertionError(sameRendering
         ? `Values have the same structure but are not reference-equal${suffix(msg)}\n\n    ${format(actual).replace(/\n/g, "\n    ")}\n`
-        : `Values are not strictly equal${suffix(msg)}\n\n    [Diff] Actual / Expected\n\n${diff(actual, expected)}\n`);
+        : `Values are not strictly equal${suffix(msg)}\n\n    [Diff] Actual / Expected\n\n${formatDiff(actual, expected)}\n`);
 }
 export function assertNotStrictEquals(actual, expected, msg) {
     if (!Object.is(actual, expected))

package/dist/test/core.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type { DescribeFunction, Hook, MockFunction, RunnerBase, TestFunction } from "./api.ts";
+export interface TestApi {
+    test: TestFunction;
+    it: TestFunction;
+    describe: DescribeFunction;
+    beforeAll: Hook;
+    afterAll: Hook;
+    beforeEach: Hook;
+    afterEach: Hook;
+    mock: MockFunction;
+}
+/** jest-style `.each` titles: printf placeholders, or `$path` for object rows. */
+export declare function formatTitle(title: string, args: unknown[], index: number): string;
+export declare function createTestApi(base: RunnerBase): TestApi;

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 {};