@uniflowed/test 0.0.0-alpha.7 → 0.0.0-alpha.9

package/index.js

@@ -13,6 +13,8 @@
 // The whole surface is importable from here, so a test file has one import.
 
 export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
+export type { ModuleFactory, ModuleNamespace } from "./internal/modules.js";
+export type { Uft } from "./internal/namespace.js";
 export type { Outcome, Result, RunOptions } from "./internal/run.js";
 export type { Site } from "./internal/frames.js";
 export type { SpyCall, SpyResult } from "./internal/spy.js";

package/internal/expect.js

@@ -104,10 +104,12 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
  * `$FlowFixMe` and whose result's result is `expect`, also `$FlowFixMe`. The
  * type that makes any of this checked is a written-out matcher interface —
  * one signature per matcher, plus `.not`, `.resolves` and `.rejects` — which
- * is what `expect`'s own annotation is waiting for. Until that exists, a
- * narrower type here would be precision nobody can reach.
+ * is what `expect`'s own annotation is waiting for, and is
+ * ubugeeei-prod/uf#402. Until that exists, a narrower type here would be
+ * precision nobody can reach.
  */
 function verdicts(received: mixed): {
+  // uf-lint-disable-next-line flow/unclear-type
   readonly [string]: (...args: $ReadOnlyArray<any>) => Verdict,
 } {
   const shown = () => render(received);
@@ -617,6 +619,15 @@ function expectValue(received: mixed): $FlowFixMe {
  * than a negated assertion around the whole object, and is the form a suite
  * being ported will already have.
  */
+// `flow/unsafe-object-assign` asks for an object spread, and a spread cannot
+// produce this value: `expect` is a *function* with matchers hanging off it,
+// and `{ ...expectValue, ...matchers }` is a plain object that a test cannot
+// call. `Object.assign` onto a callable is the only expression that makes one,
+// and the alternative the rule is really warning about — `expect.any = …`
+// afterwards — is the top-level statement the comment above rules out. What it
+// mutates is a function this module declared six lines up and exports here; no
+// object belonging to anybody else is touched.
+// uf-lint-disable-next-line flow/unsafe-object-assign
 export const expect: $FlowFixMe = Object.assign(expectValue, {
   any: asymmetric.any,
   anything: asymmetric.anything,

package/internal/frames.js

@@ -66,6 +66,49 @@ export function frameSite(frame: string): Site | null {
   return { line: line.value, column: column.value };
 }
 
+/**
+ * The file a stack frame names, or `null`.
+ *
+ * The same scan as [`frameSite`], stopping one step earlier: everything before
+ * the `:line:column` is where the code is, and what that is depends on how V8
+ * wrote the frame — `at name (/path:1:2)` when it has a function name, and
+ * `at /path:1:2` or `at async file:///path:1:2` when it does not.
+ *
+ * What comes back is whatever the frame said, a path or a URL, because those
+ * are the two things it can be and a caller resolving a module specifier
+ * against it has to tell them apart anyway.
+ */
+export function frameFile(frame: string): string | null {
+  let end = frame.length;
+  while (end > 0 && (frame[end - 1] === " " || frame[end - 1] === ")")) {
+    end -= 1;
+  }
+
+  const column = digitsBefore(frame, end);
+  if (column == null || column.start === 0 || frame[column.start - 1] !== ":") {
+    return null;
+  }
+  const line = digitsBefore(frame, column.start - 1);
+  if (line == null || line.start === 0 || frame[line.start - 1] !== ":") {
+    return null;
+  }
+
+  let text = frame.slice(0, line.start - 1);
+  const open = text.lastIndexOf("(");
+  if (open !== -1) {
+    text = text.slice(open + 1);
+  } else {
+    const at = text.lastIndexOf(" at ");
+    text = at === -1 ? text : text.slice(at + 4);
+  }
+  text = text.trim();
+  // `at async /path:1:2` — the marker belongs to the frame, not to the file.
+  if (text.startsWith("async ")) {
+    text = text.slice("async ".length).trim();
+  }
+  return text === "" ? null : text;
+}
+
 /** The run of digits ending at `end`, with where it starts. */
 function digitsBefore(
   text: string,

package/internal/modules.js

@@ -0,0 +1,430 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: standing a module in for another one.
+//
+// `uft.spyOn` replaces a method on an object a test can reach. This replaces a
+// *module*, which is the only seam a great deal of a React application has: a
+// component that imports a client and calls it at module scope, a page that
+// imports `useRouter`, a `"use server"` module a client component calls. The
+// mechanism belongs to the loader and lives in `@uniflowed/host`
+// (`module-mocks.js`); what lives here is the API, the resolution of a
+// specifier to the module it names, and the automatic stand-in.
+//
+// # When a mock takes effect
+//
+// **A mock is not hoisted.** Vitest lifts `vi.mock` above the importing file's
+// `import` declarations with a Babel pass; uf has no Babel in its pipeline and
+// `docs/architecture.md` says so on purpose, so inventing one for this would be
+// a compiler pass whose only customer is a test helper. Bun answers the same
+// question the same way, and it is the answer this package gives:
+//
+//   * every `import` declaration in a file runs before the file's first
+//     statement, so a static import is *never* affected by a `uft.mock` written
+//     below it — it already holds the real module;
+//   * `uft.mock` takes effect for every import that begins after the promise it
+//     returns settles;
+//   * so `await import("./client.js")` — after the mock — is how a test reaches
+//     the stand-in.
+//
+// A synchronous factory is installed before `uft.mock` returns, which means the
+// rule holds whether or not the promise is awaited. Awaiting is still the habit
+// worth having, because an automatic stand-in has to read the real module first
+// and cannot be installed synchronously at all.
+//
+// # What a mock does not do
+//
+// A module that has already been evaluated is not re-written. Node's registry
+// hands out a namespace that is linked into every importer, and no loader hook
+// can reach back into it — Bun's engine can, and having one API mean two things
+// on two hosts is worse than having it mean the narrower one on both. So a mock
+// affects the next import, not the last one, and `uft.resetModules` is how a
+// test gets a module evaluated again.
+
+import {
+  actualUrl,
+  defineModuleMock,
+  installInterception,
+  interceptionSupported,
+  removeModuleMock,
+  resetModuleMocks,
+  startModuleEpoch,
+} from "@uniflowed/host/module-mocks";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { UnsupportedError } from "./unsupported.js";
+import { frameFile, isInternalFrame } from "./frames.js";
+import { fn } from "./spy.js";
+
+/** The shape of a module's exports, as far as a type can say it. */
+export type ModuleNamespace = { +[string]: mixed };
+
+/**
+ * What a `uft.mock` factory hands back.
+ *
+ * `Partial<Module>` rather than `Module` because a partial mock is the common
+ * case — replace `send`, keep everything else — and rather than an unconstrained
+ * object because the whole point of a Flow-first toolchain doing this is that
+ * `{ send: 42 }` for a module whose `send` is a function is a type error at the
+ * call rather than a `TypeError` three tests later.
+ */
+export type ModuleFactory<Module> = () => Partial<Module> | Promise<Partial<Module>>;
+
+/** How deep an automatic stand-in follows nested objects. */
+const AUTOMOCK_DEPTH = 5;
+
+/**
+ * Why module interception is unavailable here, or `null` when it is available.
+ *
+ * Named as a reason rather than a boolean because the reason is what a reader
+ * needs: "this host has no synchronous module hooks" tells them the suite will
+ * work on Node, and "not implemented" tells them nothing.
+ */
+export function moduleMockingUnavailable(): string | null {
+  return interceptionSupported() ? null : unsupportedReason(hostName());
+}
+
+/** The name of the host this process is. */
+export function hostName(): string {
+  const host = globalThis as $FlowFixMe;
+  if (host.Deno != null) {
+    return "Deno";
+  }
+  if (host.process?.versions?.bun != null) {
+    return "Bun";
+  }
+  return "this host";
+}
+
+/** What to tell someone whose host cannot intercept a module. */
+export function unsupportedReason(host: string): string {
+  return (
+    `replacing a module before it is imported needs synchronous module ` +
+    `customization hooks (\`node:module\`'s \`registerHooks\`), and ${host} does ` +
+    `not provide them; run the suite on Node, or replace what the module ` +
+    `hands out with \`uft.spyOn\` or \`@uniflowed/mock\` instead`
+  );
+}
+
+/** Raise unless this host can intercept a module. */
+function requireInterception(binding: string): void {
+  const reason = moduleMockingUnavailable();
+  if (reason != null) {
+    throw new UnsupportedError(binding, reason);
+  }
+  installInterception();
+}
+
+/**
+ * The module that called into this one.
+ *
+ * A specifier is relative to the file it was written in, so that file has to be
+ * found, and a stack trace is the only place it is recorded. The frames are
+ * `--enable-source-maps`'d back to the author's own file, so what comes back is
+ * the path of the source rather than of the transform — which is exactly what a
+ * relative specifier in that source should resolve against.
+ */
+function callerURL(binding: string): string {
+  const stack = new Error("uft").stack;
+  for (const frame of (stack ?? "").split("\n").slice(1)) {
+    if (isInternalFrame(frame)) {
+      continue;
+    }
+    const file = frameFile(frame);
+    if (file == null) {
+      continue;
+    }
+    if (file.startsWith("file:")) {
+      const url = new URL(file);
+      url.search = "";
+      url.hash = "";
+      return url.href;
+    }
+    if (file.startsWith("/")) {
+      return pathToFileURL(file).href;
+    }
+  }
+  throw new UnsupportedError(
+    binding,
+    "the calling file could not be read off the stack, so a relative " +
+      "specifier has nothing to resolve against; pass an absolute path or a " +
+      "`file:` URL",
+  );
+}
+
+/**
+ * The URL a specifier names, resolved from the file that wrote it.
+ *
+ * A path is resolved as a URL, which is what an ES module specifier is; a bare
+ * specifier goes through the package resolver, so `@uniflowed/router` reaches
+ * the same file an `import` of it would.
+ */
+export function resolveSpecifier(specifier: string, parentURL: string): string {
+  if (specifier.startsWith("file:")) {
+    return specifier;
+  }
+  if (isPathSpecifier(specifier)) {
+    return new URL(specifier, parentURL).href;
+  }
+  try {
+    return pathToFileURL(createRequire(parentURL).resolve(specifier)).href;
+  } catch (error) {
+    throw new Error(`uft could not resolve "${specifier}" from ${parentURL}: ${String(error)}`);
+  }
+}
+
+/**
+ * Register a stand-in for the module `specifier` names.
+ *
+ * With a factory, the factory is what the module exports. Without one, the real
+ * module is read and every function it exports becomes a spy that records its
+ * calls and returns `undefined` — the automatic form, for a module whose shape
+ * a test wants to keep and whose behaviour it wants gone.
+ */
+export function mock<Module: ModuleNamespace>(
+  specifier: string,
+  factory?: ModuleFactory<Module>,
+): Promise<void> {
+  requireInterception("mock");
+  const url = resolveSpecifier(specifier, callerURL("mock"));
+
+  if (factory == null) {
+    return importURL(actualUrl(url, isPathSpecifier(specifier))).then((actual) => {
+      defineModuleMock(url, automock(actual, AUTOMOCK_DEPTH, new Map()));
+    });
+  }
+
+  const produced = factory();
+  if (isThenable(produced)) {
+    return (produced: $FlowFixMe).then((namespace) => {
+      defineModuleMock(url, exportsOf(specifier, namespace));
+    });
+  }
+  defineModuleMock(url, exportsOf(specifier, produced));
+  return Promise.resolve();
+}
+
+/** Stop standing in for the module `specifier` names. */
+export function unmock(specifier: string): void {
+  requireInterception("unmock");
+  removeModuleMock(resolveSpecifier(specifier, callerURL("unmock")));
+}
+
+/**
+ * The real module, whatever is registered for it.
+ *
+ * A separate instance from the one an ordinary import gets while the module is
+ * mocked — there is only one URL per module instance, and the mocked one is
+ * occupying the other. One instance per module epoch, so two calls in a row
+ * hand back the same module.
+ *
+ * It reaches past the mock for the module it *names* and for no other: the
+ * modules that one imports are resolved the way they would be anywhere else,
+ * stand-ins included. That is what makes a partial mock possible — the factory
+ * asks for the real module while its own stand-in is being built — and it is
+ * also why `importActual` of a module that imports a mocked one still sees the
+ * stand-in.
+ */
+export function importActual<Module: ModuleNamespace>(specifier: string): Promise<Module> {
+  requireInterception("importActual");
+  const url = resolveSpecifier(specifier, callerURL("importActual"));
+  return importURL(actualUrl(url, isPathSpecifier(specifier)));
+}
+
+/**
+ * The module with every function it exports replaced by a spy.
+ *
+ * The automatic form of `mock`, without registering anything: what comes back
+ * is a stand-in the caller holds, and every other importer of that module still
+ * gets whatever it got before.
+ */
+export function importMock<Module: ModuleNamespace>(specifier: string): Promise<Module> {
+  requireInterception("importMock");
+  const url = resolveSpecifier(specifier, callerURL("importMock"));
+  return importURL(actualUrl(url, isPathSpecifier(specifier))).then(
+    (actual) => (automock(actual, AUTOMOCK_DEPTH, new Map()): $FlowFixMe),
+  );
+}
+
+/**
+ * Evaluate modules again on the next import of them.
+ *
+ * "Modules" means the ones reached by a path — this project's own. A package is
+ * left alone: handing a second copy of `@uniflowed/test` to a file would give
+ * it a second registry and a second set of spies, and a reset that did that
+ * would break far more than it fixed.
+ *
+ * It does not run a mock's factory again. The factory ran when `uft.mock` was
+ * called; register the mock again to get new stand-ins out of it.
+ */
+export function resetModules(): void {
+  requireInterception("resetModules");
+  startModuleEpoch();
+}
+
+/**
+ * Forget every mock and every reset.
+ *
+ * Called by the worker before each file, because a worker serves many files and
+ * a mock that outlived its file would be a suite that passes alone and fails
+ * beside another.
+ */
+export function resetModuleState(): void {
+  resetModuleMocks();
+}
+
+/**
+ * Whether `specifier` names a file rather than a package.
+ *
+ * The same three prefixes `@uniflowed/host`'s resolve hook tests for, and
+ * deliberately not `file:`: a `file:` specifier names the URL it wants, and the
+ * one module that writes one — the generated stand-in, reaching back for its
+ * values — must land on the copy of the registry that put it there.
+ */
+function isPathSpecifier(specifier: string): boolean {
+  return specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+}
+
+/** `import()`, in one place, so the marker parameter is never spelled twice. */
+function importURL<Module>(url: string): Promise<Module> {
+  return (import(url): $FlowFixMe);
+}
+
+/** Whether `value` is a promise, or near enough for `then` to be meant. */
+function isThenable(value: mixed): boolean {
+  return (
+    value != null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value: $FlowFixMe).then === "function"
+  );
+}
+
+/**
+ * The exports a factory produced, as a plain object.
+ *
+ * Copied rather than kept, so that the export list the loader writes out is
+ * fixed at the moment the mock is registered: a factory that hands back an
+ * object it goes on adding keys to would otherwise produce a module whose
+ * exports depend on when it was first imported.
+ */
+function exportsOf(specifier: string, produced: mixed): { [string]: mixed } {
+  if (produced == null || (typeof produced !== "object" && typeof produced !== "function")) {
+    throw new TypeError(
+      `uft.mock("${specifier}"): the factory must return the module's exports as an ` +
+        `object, and it returned ${produced === null ? "null" : typeof produced}`,
+    );
+  }
+  return { ...(produced: $FlowFixMe) };
+}
+
+/**
+ * `value` with its behaviour taken out and its shape left in.
+ *
+ * The rules, which are the ones a reader has to be able to predict:
+ *
+ *   * a function becomes a spy that records its calls and returns `undefined`,
+ *     keeping its name and its prototype's methods — so a class stays `new`-able
+ *     and its methods are spies too;
+ *   * an array becomes an empty array, because a fixture list a test did not
+ *     write is a fixture list a test should not depend on;
+ *   * a plain object is followed, key by key, to [`AUTOMOCK_DEPTH`];
+ *   * a getter is kept as a getter rather than followed: reading one here would
+ *     run code the module did not expect to run yet, and would fix an answer
+ *     the getter exists to recompute;
+ *   * everything else — a string, a number, a `Map`, a `Date`, a `RegExp` — is
+ *     kept, because there is nothing in it to call.
+ */
+function automock(value: mixed, depth: number, seen: Map<mixed, mixed>): mixed {
+  if (value == null || depth <= 0) {
+    return value;
+  }
+  const already = seen.get(value);
+  if (already !== undefined) {
+    return already;
+  }
+
+  if (typeof value === "function") {
+    const spy = fn().mockName((value: $FlowFixMe).name ?? "spy");
+    seen.set(value, spy);
+    copyProperties(value, spy, depth, seen, false);
+    const prototype = (value: $FlowFixMe).prototype;
+    if (prototype != null && typeof prototype === "object") {
+      // Every own name, not only the enumerable ones: a class's methods are
+      // non-enumerable own properties of its prototype, so `Object.keys` finds
+      // none of them and the stand-in of a class would have no methods at all.
+      copyProperties(prototype, spy.prototype, depth, seen, true);
+    }
+    return spy;
+  }
+
+  if (typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const empty: Array<mixed> = [];
+    seen.set(value, empty);
+    return empty;
+  }
+  if (!isPlainish(value)) {
+    return value;
+  }
+
+  const copy: { [string]: mixed } = {};
+  seen.set(value, copy);
+  copyProperties(value, copy, depth, seen, false);
+  return copy;
+}
+
+/**
+ * Automock the properties of `from` onto `onto`.
+ *
+ * `hidden` is what separates a prototype from everything else: a class's
+ * methods are own but not enumerable, so a prototype needs every own name,
+ * while an object or a function's statics want the enumerable ones — the same
+ * set a spread or a module namespace would show.
+ */
+function copyProperties(
+  from: mixed,
+  onto: mixed,
+  depth: number,
+  seen: Map<mixed, mixed>,
+  hidden: boolean,
+): void {
+  const source = (from: $FlowFixMe);
+  const target = (onto: $FlowFixMe);
+  const names = hidden ? Object.getOwnPropertyNames(source) : Object.keys(source);
+  for (const name of names) {
+    // `constructor` on a prototype points back at the function being mocked,
+    // and rewriting it would replace the spy with a spy of the spy.
+    if (name === "constructor") {
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(source, name);
+    if (descriptor == null) {
+      continue;
+    }
+    if (!Object.hasOwn(descriptor, "value")) {
+      Object.defineProperty(target, name, descriptor);
+      continue;
+    }
+    target[name] = automock(descriptor.value, depth - 1, seen);
+  }
+}
+
+/**
+ * Whether an object is one to look inside.
+ *
+ * A module namespace, an object literal and a `null`-prototype object are; a
+ * `Map`, a `Date`, a `RegExp` and anything else with behaviour of its own are
+ * not — replacing their methods with spies would produce something that claims
+ * to be a `Date` and cannot tell the time.
+ */
+function isPlainish(value: mixed): boolean {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype || isNamespace(value);
+}
+
+/** Whether `value` is a module namespace object. */
+function isNamespace(value: mixed): boolean {
+  return (value: $FlowFixMe)[Symbol.toStringTag] === "Module";
+}

package/internal/namespace.js

@@ -18,14 +18,28 @@
 // name — two very different things one dot apart. `uft` is three characters,
 // belongs to nothing else, and is what a reader types a hundred times a file.
 //
-// What is *not* here is as deliberate. `uft.mock` intercepts a module before it
-// is imported, which needs the loader rather than the runner, and uf's loader is
-// `@uniflowed/host` — so it is a real piece of work rather than a wrapper, and
-// it is not pretended at here. A missing binding throws with what it would take;
-// a binding that silently did nothing would be worse than not having it.
+// `uft.mock` and the six names beside it intercept a module before it is
+// imported, which is the loader's job rather than the runner's: by the time the
+// runner sees an `import`, the module has been fetched, linked and evaluated.
+// So the mechanism is `@uniflowed/host`'s (`module-mocks.js`) and the API is
+// `./modules.js`'s, and this file only names them. A host that cannot provide
+// synchronous module hooks gets an `UnsupportedError` that says which host it
+// is and what to do instead — never a binding that silently does nothing.
 
+import {
+  importActual as importActualModule,
+  importMock as importMockModule,
+  mock as mockModule,
+  resetModules as resetModulesNow,
+  unmock as unmockModule,
+} from "./modules.js";
 import { clearAllMocks, fn, resetAllMocks, restoreAllMocks, spyOn } from "./spy.js";
 import * as timers from "./timers.js";
+import { UnsupportedError } from "./unsupported.js";
+
+// Declared in `./unsupported.js` rather than here, because `./modules.js` needs
+// it too and a class both halves of a pair reach for is a third module.
+export { UnsupportedError } from "./unsupported.js";
 
 /** Environment variables `stubEnv` replaced, and what they were. */
 const stubbedEnv: Map<string, string | void> = new Map();
@@ -33,24 +47,6 @@ const stubbedEnv: Map<string, string | void> = new Map();
 /** Globals `stubGlobal` replaced, and what they were. */
 const stubbedGlobals: Map<string, { readonly owned: boolean, readonly value: mixed }> = new Map();
 
-/**
- * Raised for a `uft` namespace binding that is not implemented.
- *
- * Names what the binding needs rather than only that it is missing: `uft.mock`
- * is absent because module interception belongs to the loader, and a reader who
- * knows that can decide whether to wait or to restructure the test.
- */
-export class UnsupportedError extends Error {
-  /** The binding that was called. */
-  binding: string;
-
-  constructor(binding: string, reason: string) {
-    super(`uft.${binding} is not implemented yet: ${reason}`);
-    this.name = "UnsupportedError";
-    this.binding = binding;
-  }
-}
-
 /**
  * Read the process environment, whichever host this is.
  *
@@ -190,17 +186,54 @@ export function mocked<T>(value: T): $FlowFixMe {
   return value;
 }
 
-/** Not implemented, and specific about what it would take. */
-function unsupported(binding: string, reason: string): () => empty {
-  return () => {
-    throw new UnsupportedError(binding, reason);
-  };
-}
+/**
+ * The `uft` namespace's type.
+ *
+ * Written out member by member rather than left as one `$FlowFixMe`, because
+ * the module-mocking half of it is the half a type can genuinely check: a
+ * factory that hands back the wrong shape for the module it is standing in for
+ * is an error at the call site, and that only works if `uft` has a type at all.
+ * The members that were already typed loosely keep the types they have —
+ * `typeof` reads them from their definitions, so this list cannot drift from
+ * them.
+ */
+export type Uft = {
+  readonly fn: typeof fn,
+  readonly spyOn: typeof spyOn,
+  readonly mocked: typeof mocked,
+
+  readonly clearAllMocks: typeof clearAllMocks,
+  readonly resetAllMocks: typeof resetAllMocks,
+  readonly restoreAllMocks: typeof restoreAllMocks,
+
+  readonly stubEnv: typeof stubEnv,
+  readonly unstubAllEnvs: typeof unstubAllEnvs,
+  readonly stubGlobal: typeof stubGlobal,
+  readonly unstubAllGlobals: typeof unstubAllGlobals,
+
+  readonly waitFor: typeof waitFor,
+  readonly waitUntil: typeof waitUntil,
+
+  readonly useFakeTimers: typeof timers.useFakeTimers,
+  readonly useRealTimers: typeof timers.useRealTimers,
+  readonly isFakeTimers: typeof timers.isFaked,
+  readonly advanceTimersByTime: typeof timers.advanceTimersByTime,
+  readonly advanceTimersByTimeAsync: typeof timers.advanceTimersByTimeAsync,
+  readonly advanceTimersToNextTimer: typeof timers.advanceTimersToNextTimer,
+  readonly runAllTimers: typeof timers.runAllTimers,
+  readonly runOnlyPendingTimers: typeof timers.runOnlyPendingTimers,
+  readonly getTimerCount: typeof timers.getTimerCount,
+  readonly setSystemTime: typeof timers.setSystemTime,
+  readonly getMockedSystemTime: typeof timers.getMockedSystemTime,
 
-/** The reason every module-interception binding is absent. */
-const NEEDS_LOADER =
-  "intercepting a module before it is imported belongs to the loader " +
-  "(`@uniflowed/host`), not to the runner, and uf has not wired it yet";
+  readonly mock: typeof mockModule,
+  readonly doMock: typeof mockModule,
+  readonly unmock: typeof unmockModule,
+  readonly doUnmock: typeof unmockModule,
+  readonly importActual: typeof importActualModule,
+  readonly importMock: typeof importMockModule,
+  readonly resetModules: typeof resetModulesNow,
+};
 
 /**
  * The `uft` namespace.
@@ -209,7 +242,7 @@ const NEEDS_LOADER =
  * per-instance, and freezing it means a test cannot leave a monkey-patch behind
  * for the next one.
  */
-export const uft: $FlowFixMe = Object.freeze({
+export const uft: Uft = Object.freeze({
   fn,
   spyOn,
   mocked,
@@ -240,12 +273,15 @@ export const uft: $FlowFixMe = Object.freeze({
   setSystemTime: timers.setSystemTime,
   getMockedSystemTime: timers.getMockedSystemTime,
 
-  // Module interception. Absent rather than faked; see `NEEDS_LOADER`.
-  mock: unsupported("mock", NEEDS_LOADER),
-  doMock: unsupported("doMock", NEEDS_LOADER),
-  unmock: unsupported("unmock", NEEDS_LOADER),
-  doUnmock: unsupported("doUnmock", NEEDS_LOADER),
-  importActual: unsupported("importActual", NEEDS_LOADER),
-  importMock: unsupported("importMock", NEEDS_LOADER),
-  resetModules: unsupported("resetModules", NEEDS_LOADER),
+  // Module interception. `doMock` is `mock` and `doUnmock` is `unmock`, under
+  // the names Vitest gives the un-hoisted forms: there is one form here,
+  // because uf hoists neither, and a `doMock` that was a different function
+  // would be claiming a difference that does not exist.
+  mock: mockModule,
+  doMock: mockModule,
+  unmock: unmockModule,
+  doUnmock: unmockModule,
+  importActual: importActualModule,
+  importMock: importMockModule,
+  resetModules: resetModulesNow,
 });

package/internal/unsupported.js

@@ -0,0 +1,30 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: the error a `uft` binding raises when this
+// host cannot give it.
+//
+// Its own module because two of them need it — the namespace, and the module
+// mocking in `./modules.js` that the namespace imports — and a class that both
+// of a pair of modules reaches for is a third module, not an import cycle.
+//
+// The class is exported from the package, so a test can catch it by name
+// rather than by matching on a message.
+
+/**
+ * Raised for a `uft` binding this host cannot provide.
+ *
+ * Names what the binding needs rather than only that it is missing: a reader
+ * who is told that module interception needs synchronous module hooks can
+ * decide whether to run the suite on another host or to restructure the test,
+ * and neither is a decision a bare "not implemented" supports.
+ */
+export class UnsupportedError extends Error {
+  /** The binding that was called. */
+  binding: string;
+
+  constructor(binding: string, reason: string) {
+    super(`uft.${binding} is not available: ${reason}`);
+    this.name = "UnsupportedError";
+    this.binding = binding;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.0.0-alpha.7",
+  "version": "0.0.0-alpha.9",
   "description": "The test API and worker for `uf test`: describe/it, a full matcher set, and the process uf fans test files out to.",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,6 @@
     "internal"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.0.0-alpha.7"
+    "@uniflowed/host": "0.0.0-alpha.9"
   }
 }

package/worker.js

@@ -54,6 +54,7 @@ import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { reset } from "./internal/registry.js";
+import { resetModuleState } from "./internal/modules.js";
 import { run } from "./internal/run.js";
 
 /** What `uf` sends for one file. */
@@ -139,6 +140,11 @@ function write(event: { readonly [string]: mixed }): void {
 async function runFile(request: Request, generation: number): Promise<void> {
   const started = performance.now();
   reset();
+  // Every module this file stood in for goes back, before the next file can
+  // import one of them and be handed the previous file's stand-in. A worker
+  // serves many files out of one module registry, so this is the difference
+  // between "one file at a time" and "one file's mocks at a time".
+  resetModuleState();
   output.startFile();
 
   try {