@rcompat/test 0.11.3 → 0.12.0

package/README.md

@@ -5,9 +5,9 @@ Testing library for JavaScript runtimes.
 ## What is @rcompat/test?
 
 A cross-runtime testing library with a fluent assertion API. Provides deep
-equality checks, type assertions, exception testing, and fetch interception.
-Designed to work with the `proby` test runner. Works consistently across
-Node, Deno, and Bun.
+equality checks, type assertions, exception testing, fetch interception, and
+module mocking. Designed to work with the `proby` test runner. Works
+consistently across Node, Deno, and Bun.
 
 ## Installation
 
@@ -115,12 +115,12 @@ test.case("throws", assert => {
   // check that function throws
   assert(() => {
     throw new Error("oops");
-  }).throws();
+  }).throws("oops");
 
-  // Check specific error message
+  // Check specific error type
   assert(() => {
-    throw new Error("invalid input");
-  }).throws("invalid input");
+    throw new TypeError("invalid input");
+  }).throws(TypeError);
 });
 
 test.case("tries (does not throw)", assert => {
@@ -178,6 +178,106 @@ test.ended(async () => {
 });
 ```
 
+### Grouping tests
+
+Use `test.group` to cluster related test cases together. Groups can be run
+individually via proby.
+
+```js
+import test from "@rcompat/test";
+
+test.group("addition", () => {
+  test.case("integers", assert => {
+    assert(1 + 1).equals(2);
+  });
+
+  test.case("floats", assert => {
+    assert(0.1 + 0.2).equals(0.3);
+  });
+});
+
+test.group("subtraction", () => {
+  test.case("integers", assert => {
+    assert(3 - 1).equals(2);
+  });
+});
+```
+
+Run a specific group:
+
+```bash
+npx proby math.spec.ts addition
+```
+
+### Mocking modules
+
+Use `test.mock` to replace a module's exports and `test.import` to import the
+mocked module.
+
+```js
+import test from "@rcompat/test";
+
+using math = test.mock("./math.ts", () => ({
+  add: (a, b) => 99,
+}));
+
+const { add } = await test.import("./math.ts");
+
+test.case("returns mocked value", assert => {
+  assert(add(1, 2)).equals(99);
+});
+
+test.case("tracks calls", assert => {
+  add(1, 2);
+  assert(math.add.calls.length).equals(1);
+  assert(math.add.calls[0]).equals([1, 2]);
+  assert(math.add.called).true();
+});
+```
+
+Tracked mock functions record each call as a tuple of arguments in `calls`.
+Call tracking resets between test cases.
+
+### Static mocks with proby
+
+When running tests with `proby`, you can preload mocks before a spec file is
+evaluated by adding a sibling mock file.
+
+- `foo.spec.ts` pairs with `foo.mock.ts`
+- `foo.spec.js` pairs with `foo.mock.js`
+
+`proby` loads the mock file before the spec file, so the spec's static imports
+see the mocked module immediately.
+
+```ts
+// math.ts
+export function add(a: number, b: number) {
+  return a + b;
+}
+```
+
+```ts
+// math.mock.ts
+import test from "@rcompat/test";
+
+test.mock("./math.ts", () => ({
+  add: (a: number, b: number) => 99,
+}));
+```
+
+```ts
+// math.spec.ts
+import test from "@rcompat/test";
+import { add } from "./math.ts";
+
+test.case("static mock is loaded before the spec", assert => {
+  assert(add(1, 2)).equals(99);
+});
+```
+
+Static mocks are file-scoped when run through `proby`; they do not leak into
+later spec files.
+
 ### Intercepting fetch
 
 Use `test.intercept` to block outbound fetch calls to a specific origin and
@@ -283,6 +383,45 @@ test.ended(callback: () => void | Promise<void>): void;
 
 Register a cleanup callback to run after all tests in the file.
 
+### `test.group`
+
+```ts
+test.group(name: string, fn: () => void): void;
+```
+
+Group test cases under a named scope. Groups can be targeted individually
+when running proby.
+
+| Parameter | Type       | Description                         |
+| --------- | ---------- | ----------------------------------- |
+| `name`    | `string`   | Group name, used by proby to filter |
+| `fn`      | `function` | Function containing `test.case` calls |
+
+### `test.mock`
+
+```ts
+test.mock<T extends object>(
+  specifier: string,
+  factory: (original: unknown) => T,
+): MockHandle<T>;
+```
+
+Register a module mock and return a handle to the tracked mocked exports.
+Function exports are wrapped so you can inspect `calls` and `called`.
+
+| Parameter   | Type       | Description                                  |
+| ----------- | ---------- | -------------------------------------------- |
+| `specifier` | `string`   | Module specifier to mock                     |
+| `factory`   | `function` | Returns the mocked exports for that module   |
+
+### `test.import`
+
+```ts
+test.import(specifier: string): Promise<unknown>;
+```
+
+Import a module after mocks have been registered.
+
 ### `test.intercept`
 
 ```ts
@@ -295,32 +434,10 @@ test.intercept(
 Intercept outbound fetch calls to `base_url`. Returns an `Intercept` object
 for asserting on recorded requests.
 
-| Parameter  | Type       | Description                                      |
-| ---------- | ---------- | ------------------------------------------------ |
-| `base_url` | `string`   | Origin to intercept, e.g. `"https://api.example.com"` |
-| `setup`    | `function` | Register route handlers on the setup object      |
-
-#### `Setup`
-
-| Method                          | Description                  |
-| ------------------------------- | ---------------------------- |
-| `get(path, handler)`            | Register a GET handler       |
-| `post(path, handler)`           | Register a POST handler      |
-| `put(path, handler)`            | Register a PUT handler       |
-| `patch(path, handler)`          | Register a PATCH handler     |
-| `delete(path, handler)`         | Register a DELETE handler    |
-
-Each handler receives the incoming `Request` and returns a plain object,
-which is serialized into a `Response` automatically.
-
-#### `Intercept`
-
-| Method              | Description                                          |
-| ------------------- | ---------------------------------------------------- |
-| `calls(path)`       | Number of times `path` was hit                       |
-| `requests(path)`    | Array of `Request` objects recorded for `path`       |
-| `restore()`         | Reinstate the original `globalThis.fetch`            |
-| `[Symbol.asyncDispose]` | Called automatically by `await using`            |
+| Parameter  | Type       | Description                                               |
+| ---------- | ---------- | --------------------------------------------------------- |
+| `base_url` | `string`   | Origin to intercept, e.g. `"https://api.example.com"`    |
+| `setup`    | `function` | Register route handlers on the setup object               |
 
 ### `test.extend`
 
@@ -333,9 +450,31 @@ test.extend<Subject, Extensions>(
 Create a new test object with custom assertion methods mixed into the
 asserter.
 
-| Parameter | Type       | Description                                              |
-| --------- | ---------- | -------------------------------------------------------- |
-| `factory` | `function` | Returns extra methods to attach to each `Assert` instance |
+| Parameter | Type       | Description                                                |
+| --------- | ---------- | ---------------------------------------------------------- |
+| `factory` | `function` | Returns extra methods to attach to each `Assert` instance  |
+
+#### `Setup`
+
+| Method                 | Description               |
+| ---------------------- | ------------------------- |
+| `get(path, handler)`   | Register a GET handler    |
+| `post(path, handler)`  | Register a POST handler   |
+| `put(path, handler)`   | Register a PUT handler    |
+| `patch(path, handler)` | Register a PATCH handler  |
+| `delete(path, handler)`| Register a DELETE handler |
+
+Each handler receives the incoming `Request` and returns a plain object,
+which is serialized into a `Response` automatically.
+
+#### `Intercept`
+
+| Method                  | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `calls(path)`           | Number of times `path` was hit                  |
+| `requests(path)`        | Array of `Request` objects recorded for `path`  |
+| `restore()`             | Reinstate the original `globalThis.fetch`       |
+| `[Symbol.asyncDispose]` | Called automatically by `await using`           |
 
 ### `Asserter`
 
@@ -406,7 +545,7 @@ import E from "@rcompat/test/E";
 E(error: unknown): { message: string };
 ```
 
-Extract error message from unknown error type.
+Extract error data from unknown error types.
 
 ## Examples
 

package/lib/private/Suite.d.ts

@@ -5,9 +5,10 @@ import type { FileRef } from "@rcompat/fs";
 export default class Suite {
     #private;
     constructor(file: FileRef);
-    test(name: string, body: Body): void;
+    test(name: string, body: Body, group?: string): void;
     ended(end: End): void;
     get file(): FileRef;
+    between(fn: () => void): void;
     run(): AsyncGenerator<Test, void, unknown>;
     end(): Promise<void>;
 }

package/lib/private/Suite.js

@@ -3,11 +3,12 @@ export default class Suite {
     #file;
     #tests = [];
     #ends = [];
+    #between = [];
     constructor(file) {
         this.#file = file;
     }
-    test(name, body) {
-        this.#tests.push(new Test(name, body));
+    test(name, body, group) {
+        this.#tests.push(new Test(name, body, group));
     }
     ended(end) {
         this.#ends.push(end);
@@ -15,9 +16,15 @@ export default class Suite {
     get file() {
         return this.#file;
     }
+    between(fn) {
+        this.#between.push(fn);
+    }
     async *run() {
         for (const test of this.#tests) {
             yield await test.run();
+            for (const fn of this.#between) {
+                fn();
+            }
         }
     }
     async end() {

package/lib/private/Test.d.ts

@@ -2,8 +2,9 @@ import type Body from "#Body";
 import Result from "#Result";
 export default class Test {
     #private;
-    constructor(name: string, body: Body);
+    constructor(name: string, body: Body, group?: string);
     get name(): string;
+    get group(): string | undefined;
     get results(): Result<unknown>[];
     report<T>(actual: T, expected: T, passed: boolean): void;
     run(): Promise<this>;

package/lib/private/Test.js

@@ -4,13 +4,18 @@ export default class Test {
     #name;
     #body;
     #results = [];
-    constructor(name, body) {
+    #group;
+    constructor(name, body, group) {
         this.#name = name;
         this.#body = body;
+        this.#group = group;
     }
     get name() {
         return this.#name;
     }
+    get group() {
+        return this.#group;
+    }
     get results() {
         return this.#results;
     }

package/lib/private/fixtures/math.d.ts

@@ -0,0 +1,2 @@
+export declare function add(a: number, b: number): number;
+//# sourceMappingURL=math.d.ts.map

package/lib/private/fixtures/math.js

@@ -0,0 +1,5 @@
+export function add(a, b) {
+    return a + b;
+}
+;
+//# sourceMappingURL=math.js.map

package/lib/private/import.d.ts

@@ -0,0 +1,2 @@
+export default function mock_import(specifier: string): Promise<any>;
+//# sourceMappingURL=import.d.ts.map

package/lib/private/import.js

@@ -0,0 +1,4 @@
+export default function mock_import(specifier) {
+    return import(`${specifier}?mock=${Date.now()}`);
+}
+//# sourceMappingURL=import.js.map

package/lib/private/index.d.ts

@@ -5,6 +5,8 @@ import type Env from "#Env";
 import type Result from "#Result";
 import type Test from "#Test";
 import type { ExtendedTest, Factory } from "#extend";
+import mock from "#mock";
+import import_ from "#import";
 declare const _default: {
     intercept: (base_url: string, setup: (setup: {
         get(path: string, handler: (request: Request) => unknown): void;
@@ -21,6 +23,9 @@ declare const _default: {
     extend<Subject, Extensions>(factory: Factory<Subject, Extensions>): ExtendedTest<Extensions>;
     case(name: string, body: Body): void;
     ended(end: End): void;
+    group(name: string, fn: () => void): void;
+    mock: typeof mock;
+    import: typeof import_;
 };
 export default _default;
 export type { Asserter, Env, ExtendedTest, Result, Test };

package/lib/private/index.js

@@ -1,6 +1,8 @@
 import extend from "#extend";
 import repository from "#repository";
 import intercept from "#intercept";
+import mock from "#mock";
+import import_ from "#import";
 const base = {
     case(name, body) {
         repository.put(name, body);
@@ -8,6 +10,11 @@ const base = {
     ended(end) {
         repository.ended(end);
     },
+    group(name, fn) {
+        repository.group(name, fn);
+    },
+    mock,
+    import: import_,
 };
 export default {
     ...base,

package/lib/private/mock.d.ts

@@ -0,0 +1,14 @@
+type AnyFn = (...args: any[]) => any;
+type Tracked<F extends AnyFn> = F & {
+    calls: Parameters<F>[];
+    readonly called: boolean;
+};
+type MockHandle<T extends object> = {
+    [K in keyof T]: T[K] extends AnyFn ? Tracked<T[K]> : T[K];
+} & {
+    restore(): void;
+    [Symbol.dispose](): void;
+};
+export default function mock<T extends object>(specifier: string, factory: (original: unknown) => T): MockHandle<T>;
+export {};
+//# sourceMappingURL=mock.d.ts.map

package/lib/private/mock.js

@@ -0,0 +1,87 @@
+import repository from "#repository";
+import is from "@rcompat/is";
+import module from "node:module";
+let loader_registered = false;
+const MARK = "std:test/mock";
+const clean = (specifier) => specifier.split("?")[0];
+const track = (fn) => {
+    const calls = [];
+    const tracked = ((...args) => {
+        calls.push(args);
+        return fn(...args);
+    });
+    tracked.calls = calls;
+    Object.defineProperty(tracked, "called", {
+        get: () => calls.length > 0,
+    });
+    return tracked;
+};
+const hooks = {
+    resolve(specifier, context, next) {
+        const id = clean(specifier);
+        if (!repository.mocks.has(id)) {
+            return next(specifier, context);
+        }
+        const resolved = next(id, context);
+        const url = new URL(resolved.url);
+        url.searchParams.set(MARK, id);
+        return {
+            ...resolved,
+            shortCircuit: true,
+            url: url.href,
+        };
+    },
+    load(url, context, next) {
+        const parsed = new URL(url);
+        const id = parsed.searchParams.get(MARK);
+        if (id === null) {
+            return next(url, context);
+        }
+        const tracked = repository.mocks.get(id);
+        if (tracked === undefined)
+            throw new Error(`mock not found for ${id}`);
+        const exports = Object.keys(tracked);
+        const source = `
+      import repository from "@rcompat/test/repository";
+      const tracked = repository.mocks.get(${JSON.stringify(id)});
+      if (tracked === undefined) {
+        throw new Error(${JSON.stringify(`mock not found for ${id}`)});
+      }
+      ${exports.map(k => `export const ${k} = tracked[${JSON.stringify(k)}];`).join("\n")}
+    `;
+        return {
+            format: "module",
+            shortCircuit: true,
+            source,
+        };
+    },
+};
+export default function mock(specifier, factory) {
+    if (!loader_registered) {
+        module.registerHooks(hooks);
+        loader_registered = true;
+    }
+    const id = clean(specifier);
+    const mocked = factory({});
+    const tracked = Object.fromEntries(Object.entries(mocked).map(([k, v]) => [
+        k,
+        is.function(v) ? track(v) : v,
+    ]));
+    repository.mocks.set(id, tracked);
+    repository.between(() => {
+        for (const v of Object.values(tracked)) {
+            if (is.function(v) && "calls" in v) {
+                v.calls.length = 0;
+            }
+        }
+    });
+    return Object.assign(tracked, {
+        restore() {
+            repository.mocks.delete(id);
+        },
+        [Symbol.dispose]() {
+            this.restore();
+        },
+    });
+}
+//# sourceMappingURL=mock.js.map

package/lib/private/repository.d.ts

@@ -4,7 +4,10 @@ import Suite from "#Suite";
 import type { FileRef } from "@rcompat/fs";
 declare class Repository {
     #private;
+    get mocks(): Map<string, unknown>;
     put(name: string, body: Body): void;
+    group(name: string, fn: () => void): void;
+    between(fn: () => void): void;
     ended(end: End): void;
     suite(file: FileRef): void;
     reset(): void;

package/lib/private/repository.js

@@ -1,11 +1,24 @@
 import Suite from "#Suite";
 class Repository {
     #suites = [];
+    #current_group;
+    #mocks = new Map();
     get #suite() {
         return this.#suites.at(-1);
     }
+    get mocks() {
+        return this.#mocks;
+    }
     put(name, body) {
-        this.#suite.test(name, body);
+        this.#suite.test(name, body, this.#current_group);
+    }
+    group(name, fn) {
+        this.#current_group = name;
+        fn();
+        this.#current_group = undefined;
+    }
+    between(fn) {
+        this.#suite.between(fn);
     }
     ended(end) {
         this.#suite.ended(end);
@@ -15,6 +28,7 @@ class Repository {
     }
     reset() {
         this.#suites = [];
+        this.#mocks = new Map();
     }
     *next() {
         for (const suite of this.#suites) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcompat/test",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "Standard library testing",
   "bugs": "https://github.com/rcompat/rcompat/issues",
   "license": "MIT",
@@ -14,42 +14,45 @@
     "url": "https://github.com/rcompat/rcompat",
     "directory": "packages/test"
   },
+  "dependencies": {
+    "@rcompat/is": "^0.6.0"
+  },
   "devDependencies": {
-    "@rcompat/fs": "^0.27.1",
-    "@rcompat/type": "^0.10.0"
+    "@rcompat/fs": "^0.28.0",
+    "@rcompat/type": "^0.11.0"
   },
   "type": "module",
   "imports": {
     "#mask/*": {
-      "apekit": "./src/private/mask/*.ts",
+      "source": "./src/private/mask/*.ts",
       "default": "./lib/private/mask/*.js"
     },
     "#types/*": {
-      "apekit": "./src/private/types/*.ts",
+      "source": "./src/private/types/*.ts",
       "default": "./lib/private/types/*.js"
     },
     "#*": {
-      "apekit": "./src/private/*.ts",
+      "source": "./src/private/*.ts",
       "default": "./lib/private/*.js"
     }
   },
   "exports": {
     "./mask/*": {
-      "apekit": "./src/public/mask/*.ts",
+      "source": "./src/public/mask/*.ts",
       "default": "./lib/public/mask/*.js"
     },
     "./*": {
-      "apekit": "./src/public/*.ts",
+      "source": "./src/public/*.ts",
       "default": "./lib/public/*.js"
     },
     ".": {
-      "apekit": "./src/public/index.ts",
+      "source": "./src/public/index.ts",
       "default": "./lib/public/index.js"
     }
   },
   "scripts": {
     "build": "npm run clean && tsc",
-    "test": "npm run build && npx proby",
+    "test": "npx proby",
     "clean": "rm -rf ./lib"
   }
 }