@uniflowed/test 0.1.0 → 0.3.0

package/index.js

@@ -26,7 +26,7 @@ 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";
+export type { SpyCall, SpyResult, SpySettledResult } from "./internal/spy.js";
 export type { Strictness } from "./internal/equality.js";
 
 export {

package/internal/equality.js

@@ -34,7 +34,8 @@ const MAX_RENDER_DEPTH = 6;
 /** Most entries of a collection the renderer shows before eliding. */
 const MAX_RENDER_ENTRIES = 32;
 
-function isObject(value: mixed): boolean {
+/** Whether `value` is an object, as a refinement the checker can follow. */
+function isObject(value: mixed): value is interface {} {
   return typeof value === "object" && value !== null;
 }
 
@@ -51,8 +52,8 @@ function tag(value: mixed): string {
  */
 function ownKeys(value: interface {}, strictness: Strictness): Array<string | symbol> {
   const strings = Object.keys(value).sort();
-  const symbols = Object.getOwnPropertySymbols(value).filter((symbol) =>
-    Object.prototype.propertyIsEnumerable.call(value, symbol),
+  const symbols = Object.getOwnPropertySymbols(value).filter(
+    (symbol) => Object.getOwnPropertyDescriptor(value, symbol)?.enumerable === true,
   );
   const keys: Array<string | symbol> = [...strings, ...symbols];
   if (strictness === "strict") {
@@ -199,7 +200,7 @@ export function equals(
     return false;
   }
   for (const key of leftKeys) {
-    if (!Object.prototype.hasOwnProperty.call(right, key)) {
+    if (!Object.hasOwn(right, key)) {
       return false;
     }
     if (!equals((left as $FlowFixMe)[key], (right as $FlowFixMe)[key], nested, strictness)) {
@@ -233,10 +234,12 @@ export function matchesObject(received: mixed, expected: mixed, seen: Array<Pair
     if (!Array.isArray(received) || received.length !== expected.length) {
       return false;
     }
-    return expected.every((item, index) => matchesObject(received[index], item, nested));
+    return expected.every((item: mixed, index: number) =>
+      matchesObject(received[index], item, nested),
+    );
   }
   for (const key of ownKeys(expected as $FlowFixMe, "loose")) {
-    if (!Object.prototype.hasOwnProperty.call(received, key)) {
+    if (!Object.hasOwn(received, key)) {
       return false;
     }
     if (!matchesObject((received as $FlowFixMe)[key], (expected as $FlowFixMe)[key], nested)) {

package/internal/expect.js

@@ -242,14 +242,6 @@ export type Expectation = Matchers<void> & {
  */
 export type Expect = {
   (received: mixed): Expectation,
-  // `flow/unclear-type` reads source text rather than an AST, and the shape it
-  // recognises as a property key rather than a type is a name at the start of
-  // a line or straight after `{`, `,` or `;`. `readonly any:` is neither, so
-  // the rule reports Jest's, Vitest's and Sinon's name for this matcher as an
-  // `any` type. The rule's own comment already lists `@uniflowed/test`'s
-  // `expect.any` among the false positives it exists to avoid; this is the one
-  // spelling it still cannot see past.
-  // uf-lint-disable-next-line flow/unclear-type
   readonly any: (constructor: mixed) => AsymmetricMatcher,
   readonly anything: () => AsymmetricMatcher,
   readonly objectContaining: (expected: interface {}) => AsymmetricMatcher,
@@ -277,7 +269,7 @@ function propertyAt(
     if (current == null) {
       return { found: false, value: undefined };
     }
-    if (!Object.prototype.hasOwnProperty.call(current as $FlowFixMe, key)) {
+    if (!Object.hasOwn(current as $FlowFixMe, key)) {
       return { found: false, value: undefined };
     }
     current = (current as $FlowFixMe)[key];
@@ -585,8 +577,8 @@ function verdicts(received: mixed): {
       requireSpy("toHaveBeenCalledWith");
       const calls = spyCalls();
       return simple(
-        calls.some((call) => equals([...call.args], [...args])),
-        `to have been called with ${render(args)}; the calls were ${render(calls.map((call) => call.args))}`,
+        calls.some((call) => equals([...call], [...args])),
+        `to have been called with ${render(args)}; the calls were ${render(calls)}`,
         args,
       );
     },
@@ -595,8 +587,8 @@ function verdicts(received: mixed): {
       const calls = spyCalls();
       const last = calls.length === 0 ? undefined : calls[calls.length - 1];
       return simple(
-        last != null && equals([...last.args], [...args]),
-        `to have last been called with ${render(args)}, not ${render(last == null ? undefined : last.args)}`,
+        last != null && equals([...last], [...args]),
+        `to have last been called with ${render(args)}, not ${render(last)}`,
         args,
       );
     },
@@ -655,6 +647,7 @@ function verdicts(received: mixed): {
         expected: render(value),
         received: render(actual),
         failure: () => `expected ${render(name)} to be ${render(value)}, not ${render(actual)}`,
+        negatedFailure: () => `expected ${render(name)} not to be ${render(value)}`,
       };
     },
     toHaveClass: (...names: $ReadOnlyArray<mixed>) => {
@@ -666,6 +659,8 @@ function verdicts(received: mixed): {
         expected: render(wanted),
         received: render(classes),
         failure: () => `expected the class list ${render(classes)} to include ${render(wanted)}`,
+        negatedFailure: () =>
+          `expected the class list ${render(classes)} not to include ${render(wanted)}`,
       };
     },
     toHaveTextContent: (expected: mixed) => {
@@ -678,6 +673,8 @@ function verdicts(received: mixed): {
         expected: render(expected),
         received: render(text),
         failure: () => `expected the text ${render(text)} to contain ${render(expected)}`,
+        negatedFailure: () =>
+          `expected the text ${render(text)} not to contain ${render(expected)}`,
       };
     },
     toHaveValue: (expected: mixed) => {
@@ -688,11 +685,12 @@ function verdicts(received: mixed): {
         expected: render(expected),
         received: render(actual),
         failure: () => `expected the value ${render(actual)} to be ${render(expected)}`,
+        negatedFailure: () => `expected the value not to be ${render(expected)}`,
       };
     },
     toHaveNoAxeViolations: async (options: mixed) => {
       const node = element("toHaveNoAxeViolations");
-      const found = await auditElement(node, (options: $FlowFixMe));
+      const found = await auditElement(node, options as $FlowFixMe);
       const named = violationIds(found);
       return {
         pass: found.length === 0,
@@ -814,58 +812,114 @@ function isDisabled(node: Element): boolean {
  * `negated` decides which message a failing verdict raises, which is all of
  * what `.not` is.
  *
- * # Why the object is built rather than written
+ * # Why the matchers live on a prototype
  *
- * `.not` has to be reached lazily or building an expectation would build its
- * negation, which would build *its* negation, forever. A lazily installed
- * property is not something an object literal carries, so the value is
- * completed with `Object.defineProperty` after it exists — and an object
- * completed after the fact is not one Flow can check a literal against. That
- * is what this `$FlowFixMe` is, and it now covers a construction rather than a
- * published type: [`expectValue`] states the real one, and the checker holds
- * every caller to it.
+ * `expect` is called once per assertion, and building its answer used to be
+ * the largest single cost of a passing assertion: the whole verdict table and a
+ * wrapper for each of its forty-one entries, eighty-odd closures, to call one
+ * of them. On a suite of 1,000 cases and 2,000 assertions that was about a
+ * twentieth of a worker's CPU, spent on functions nobody called.
+ *
+ * So the object carries only what differs between two assertions — the value
+ * and the polarity — and every matcher is a getter on one shared prototype,
+ * built the first time `expect` is used. The getter hands back a function
+ * closed over the object it was read from, rather than being a method that
+ * reads `this`: `const { toBe } = expect(1)` and `[1, 2].forEach(expect(n).not.toBe)`
+ * keep working, because the function a destructuring or a callback receives is
+ * already bound, which is what they got when every matcher was an own closure.
+ * The table is still built per *call*, from [`verdicts`], so a matcher still
+ * sees the one received value it was asked about and nothing else.
+ *
+ * `.not` is a getter on the same prototype for the reason it always was
+ * lazy: an expectation that built its negation would build *its* negation,
+ * forever. `.resolves` and `.rejects` are on a second prototype that only
+ * [`expectValue`]'s object has, so `expect(p).not.resolves` stays what it was —
+ * not a thing.
  */
-function bind(received: mixed, negated: boolean): $FlowFixMe {
-  const table = verdicts(received);
+type Bound = { readonly received: mixed, readonly negated: boolean, ... };
+
+/** The two prototypes, built on first use; see [`bind`]. */
+type Prototypes = {| readonly bound: interface {}, readonly root: interface {} |};
+let prototypes: Prototypes | null = null;
+
+/** A getter for matcher `name`, handing back a function bound to its object. */
+function matcherGetter(name: string): (this: Bound) => (...args: $ReadOnlyArray<mixed>) => mixed {
+  return function (this: Bound) {
+    const self = this;
+    return (...args: $ReadOnlyArray<mixed>) => apply(self, name, args);
+  };
+}
+
+function negation(this: Bound): mixed {
+  return bind(this.received, !this.negated);
+}
+
+function resolution(this: Bound): mixed {
+  return settled(this.received, "resolve", false);
+}
+
+function rejection(this: Bound): mixed {
+  return settled(this.received, "reject", false);
+}
+
+function matcherPrototypes(): Prototypes {
+  if (prototypes != null) {
+    return prototypes;
+  }
   const bound: $FlowFixMe = {};
-  for (const name of Object.keys(table)) {
-    const decide = (verdict: Verdict) => {
-      if (verdict.pass !== negated) {
-        return undefined;
-      }
-      const message = negated ? verdict.negatedFailure() : verdict.failure();
-      throw new AssertionError(
-        message,
-        name,
-        verdict.expected ?? "",
-        verdict.received ?? render(received),
-      );
-    };
-    bound[name] = (...args: $ReadOnlyArray<mixed>) => {
-      const verdict = table[name](...args);
-      // A matcher whose engine is asynchronous answers with a promise of a
-      // verdict, and the promise is handed straight back rather than hidden.
-      //
-      // Hiding it was the alternative and it cannot be done: the only way to
-      // present an asynchronous answer synchronously is to decide before it
-      // arrives, which is deciding without it. What the promise costs is a
-      // forgotten `await`, and that case is not silent either — the rejection
-      // reaches the worker's unhandled-rejection handler, which fails the file
-      // the promise was created in and prints this same message. A missing
-      // `await` on a passing audit is the one case nothing reports, and it is
-      // the case where nothing happened.
-      //
-      // `instanceof Promise` rather than a `then` test, and it is safe for a
-      // reason that would not survive being generalised: every entry in the
-      // table is written in this file, so the only promise that can arrive
-      // here is one an `async` function in this module made, in this realm. A
-      // matcher registered from outside — which `@uniflowed/test` has no API
-      // for, deliberately — could hand back a foreign thenable, and this line
-      // would be the thing to revisit.
-      return verdict instanceof Promise ? verdict.then(decide) : decide(verdict);
-    };
+  for (const name of Object.keys(verdicts(undefined))) {
+    Object.defineProperty(bound, name, { get: matcherGetter(name) });
   }
-  Object.defineProperty(bound, "not", { get: () => bind(received, !negated) });
+  Object.defineProperty(bound, "not", { get: negation });
+  const root: $FlowFixMe = Object.create(bound);
+  Object.defineProperty(root, "resolves", { get: resolution });
+  Object.defineProperty(root, "rejects", { get: rejection });
+  prototypes = { bound, root };
+  return prototypes;
+}
+
+/** Decide matcher `name` on `bound`'s value, raising when it does not hold. */
+function apply(bound: Bound, name: string, args: $ReadOnlyArray<mixed>): mixed {
+  const { received, negated } = bound;
+  const decide = (verdict: Verdict) => {
+    if (verdict.pass !== negated) {
+      return undefined;
+    }
+    const message = negated ? verdict.negatedFailure() : verdict.failure();
+    throw new AssertionError(
+      message,
+      name,
+      verdict.expected ?? "",
+      verdict.received ?? render(received),
+    );
+  };
+  const verdict = verdicts(received)[name](...args);
+  // A matcher whose engine is asynchronous answers with a promise of a
+  // verdict, and the promise is handed straight back rather than hidden.
+  //
+  // Hiding it was the alternative and it cannot be done: the only way to
+  // present an asynchronous answer synchronously is to decide before it
+  // arrives, which is deciding without it. What the promise costs is a
+  // forgotten `await`, and that case is not silent either — the rejection
+  // reaches the worker's unhandled-rejection handler, which fails the file
+  // the promise was created in and prints this same message. A missing
+  // `await` on a passing audit is the one case nothing reports, and it is
+  // the case where nothing happened.
+  //
+  // `instanceof Promise` rather than a `then` test, and it is safe for a
+  // reason that would not survive being generalised: every entry in the
+  // table is written in this file, so the only promise that can arrive
+  // here is one an `async` function in this module made, in this realm. A
+  // matcher registered from outside — which `@uniflowed/test` has no API
+  // for, deliberately — could hand back a foreign thenable, and this line
+  // would be the thing to revisit.
+  return verdict instanceof Promise ? verdict.then(decide) : decide(verdict);
+}
+
+function bind(received: mixed, negated: boolean): $FlowFixMe {
+  const bound: $FlowFixMe = Object.create(matcherPrototypes().bound);
+  bound.received = received;
+  bound.negated = negated;
   return bound;
 }
 
@@ -938,11 +992,9 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
  * received, for the reasons this module's header sets out.
  */
 function expectValue(received: mixed): Expectation {
-  const expectation: $FlowFixMe = bind(received, false);
-  Object.defineProperty(expectation, "resolves", {
-    get: () => settled(received, "resolve", false),
-  });
-  Object.defineProperty(expectation, "rejects", { get: () => settled(received, "reject", false) });
+  const expectation: $FlowFixMe = Object.create(matcherPrototypes().root);
+  expectation.received = received;
+  expectation.negated = false;
   return expectation;
 }
 

package/internal/frames.js

@@ -195,3 +195,181 @@ export function userFrames(stack: string | null | void): string | null {
   const frames = lines.slice(1).filter((frame) => !isInternalFrame(frame));
   return frames.length === 0 ? head : [head, ...frames].join("\n");
 }
+
+/**
+ * A V8 call site, as much of it as [`callerSite`] reads.
+ *
+ * Written out rather than imported: there is no library definition for V8's
+ * structured stack API, and these four methods are all it asks of one.
+ */
+type CallSite = interface {
+  getFileName(): ?string,
+  getLineNumber(): ?number,
+  getColumnNumber(): ?number,
+};
+
+/** The piece of `node:module`'s source-map API [`callerSite`] needs. */
+type SourceMapEntry = {|
+  readonly originalLine?: number,
+  readonly originalColumn?: number,
+  readonly originalSource?: string,
+|};
+type FindSourceMap = (
+  file: string,
+) => ?interface { findEntry(line: number, column: number): SourceMapEntry };
+
+/**
+ * `node:module`'s `findSourceMap` when the host is Node with source maps on;
+ * `false` when the structured path must not be taken; `undefined` until asked.
+ *
+ * Asked once per process: the host does not change under a running worker.
+ */
+let nodeSourceMaps: FindSourceMap | false | void;
+
+/**
+ * How to map a generated position the way Node's own stack traces do, or
+ * `false` when this host's stacks cannot be reproduced from call sites.
+ *
+ * Node only. Bun and Deno implement the call-site API too, but whether their
+ * call sites carry the generated position or the mapped one is theirs to
+ * decide and has changed between releases, so they keep the string path,
+ * whose answer is by construction the one their `.stack` prints. A browser
+ * has no `process` at all.
+ */
+function sourceMapsForCallSites(): FindSourceMap | false {
+  if (nodeSourceMaps !== undefined) {
+    return nodeSourceMaps;
+  }
+  const host: $FlowFixMe = globalThis;
+  const process = host.process;
+  const isNode =
+    typeof process?.versions?.node === "string" &&
+    process.versions.bun == null &&
+    host.Deno == null &&
+    typeof process.getBuiltinModule === "function" &&
+    typeof Error.captureStackTrace === "function";
+  if (!isNode) {
+    nodeSourceMaps = false;
+    return false;
+  }
+  const findSourceMap = process.getBuiltinModule("node:module")?.findSourceMap;
+  nodeSourceMaps =
+    typeof findSourceMap === "function"
+      ? // Only while Node applies source maps to its own stacks: with them off
+        // a `.stack` prints the generated position, and so must this.
+        (file) => (process.sourceMapsEnabled === true ? findSourceMap(file) : null)
+      : false;
+  return nodeSourceMaps;
+}
+
+/**
+ * The first position outside the runner on the stack of the call to `skip`,
+ * as `firstUserSite(new Error().stack)` would read it — or `undefined` when
+ * this host cannot answer that way, and the caller should build the string.
+ *
+ * # Why not simply read `.stack`
+ *
+ * Because it is the most expensive line in registering a test. `describe` and
+ * `it` ask where they were called from, once per case, and on Node with
+ * `--enable-source-maps` — which every `uf test` worker runs with — the string
+ * `.stack` is built by mapping *every* frame through its module's source map
+ * and printing each one, to read back one line and column from the first that
+ * is not the runner's. On a suite of 50 files and 1,000 cases that was about a
+ * sixth of a worker's CPU.
+ *
+ * V8 hands the same frames over unprinted to a `prepareStackTrace` installed
+ * for the one capture, and only the frame the answer comes from is mapped,
+ * with the lookup Node's printer itself uses — `findSourceMap(file)` then
+ * `findEntry(line - 1, column - 1)`, falling back to the generated position
+ * when there is no map or no entry — so the number is the one the string would
+ * have carried. `packages/test/registration-site.test.js` holds the two paths
+ * to that.
+ */
+export function callerSite(skip: (...args: $ReadOnlyArray<empty>) => mixed): Site | null | void {
+  const findSourceMap = sourceMapsForCallSites();
+  if (findSourceMap === false) {
+    return undefined;
+  }
+  const errors: $FlowFixMe = Error;
+  const limit: mixed = errors.stackTraceLimit;
+  const full = typeof limit === "number" ? limit : 0;
+  // A few frames first. The caller of a registration is two or three frames
+  // above it — `it`, the modifier or `each` wrapper, `addCase` — and V8's cost
+  // is per frame it materialises, so the whole default ten is walked only for
+  // the rare caller that is deeper than that.
+  const shallow = Math.min(full, SHALLOW_FRAMES);
+  const first = readCallSites(skip, shallow);
+  if (first === undefined) {
+    return undefined;
+  }
+  const found = firstUserCallSite(first, findSourceMap);
+  if (found != null || first.length < shallow || shallow === full) {
+    return found;
+  }
+  const again = readCallSites(skip, full);
+  return again === undefined ? undefined : firstUserCallSite(again, findSourceMap);
+}
+
+/** How many frames [`callerSite`] asks for before it asks for all of them. */
+const SHALLOW_FRAMES = 4;
+
+/** Hands V8's call sites back unprinted; one function, so none is made per capture. */
+function unprinted(_error: mixed, sites: $ReadOnlyArray<CallSite>): $ReadOnlyArray<CallSite> {
+  return sites;
+}
+
+/**
+ * Up to `limit` call sites above `skip`, or `undefined` when the host does not
+ * hand them over.
+ */
+function readCallSites(
+  skip: (...args: $ReadOnlyArray<empty>) => mixed,
+  limit: number,
+): $ReadOnlyArray<CallSite> | void {
+  const errors: $FlowFixMe = Error;
+  const prepare = errors.prepareStackTrace;
+  const before = errors.stackTraceLimit;
+  const holder: $FlowFixMe = {};
+  try {
+    errors.prepareStackTrace = unprinted;
+    errors.stackTraceLimit = limit;
+    errors.captureStackTrace(holder, skip);
+    // Read inside the `try`: V8 formats `stack` lazily, on first access, and
+    // with whatever `prepareStackTrace` is installed *then*. What comes back is
+    // what `unprinted` returned, which V8 does not type.
+    const sites: $FlowFixMe = holder.stack;
+    return Array.isArray(sites) ? sites : undefined;
+  } finally {
+    errors.prepareStackTrace = prepare;
+    errors.stackTraceLimit = before;
+  }
+}
+
+/** The first of `sites` outside the runner, mapped as Node maps a printed frame. */
+function firstUserCallSite(
+  sites: $ReadOnlyArray<CallSite>,
+  findSourceMap: FindSourceMap,
+): Site | null {
+  for (const site of sites) {
+    const file = site.getFileName();
+    if (file == null || isInternalFrame(file)) {
+      continue;
+    }
+    const line = site.getLineNumber();
+    const column = site.getColumnNumber();
+    if (line == null || column == null) {
+      continue;
+    }
+    const entry = findSourceMap(file)?.findEntry(line - 1, column - 1);
+    if (
+      entry?.originalSource != null &&
+      entry.originalSource !== "" &&
+      entry.originalLine != null &&
+      entry.originalColumn != null
+    ) {
+      return { line: entry.originalLine + 1, column: entry.originalColumn + 1 };
+    }
+    return { line, column };
+  }
+  return null;
+}

package/internal/modules.js

@@ -57,7 +57,7 @@ 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 };
+export type ModuleNamespace = { readonly [string]: mixed };
 
 /**
  * What a `uft.mock` factory hands back.
@@ -181,7 +181,7 @@ export function resolveSpecifier(specifier: string, parentURL: string): string {
  * 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>(
+export function mock<Module extends ModuleNamespace>(
   specifier: string,
   factory?: ModuleFactory<Module>,
 ): Promise<void> {
@@ -189,14 +189,14 @@ export function mock<Module: ModuleNamespace>(
   const url = resolveSpecifier(specifier, callerURL("mock"));
 
   if (factory == null) {
-    return importURL(actualUrl(url, isPathSpecifier(specifier))).then((actual) => {
+    return importURL<ModuleNamespace>(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) => {
+    return (produced as $FlowFixMe).then((namespace) => {
       defineModuleMock(url, exportsOf(specifier, namespace));
     });
   }
@@ -225,7 +225,7 @@ export function unmock(specifier: string): void {
  * 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> {
+export function importActual<Module extends ModuleNamespace>(specifier: string): Promise<Module> {
   requireInterception("importActual");
   const url = resolveSpecifier(specifier, callerURL("importActual"));
   return importURL(actualUrl(url, isPathSpecifier(specifier)));
@@ -238,11 +238,11 @@ export function importActual<Module: ModuleNamespace>(specifier: string): Promis
  * 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> {
+export function importMock<Module extends 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),
+  return importURL<ModuleNamespace>(actualUrl(url, isPathSpecifier(specifier))).then(
+    (actual) => automock(actual, AUTOMOCK_DEPTH, new Map()) as $FlowFixMe,
   );
 }
 
@@ -287,7 +287,7 @@ function isPathSpecifier(specifier: string): boolean {
 
 /** `import()`, in one place, so the marker parameter is never spelled twice. */
 function importURL<Module>(url: string): Promise<Module> {
-  return (import(url): $FlowFixMe);
+  return import(url) as $FlowFixMe;
 }
 
 /** Whether `value` is a promise, or near enough for `then` to be meant. */
@@ -295,7 +295,7 @@ function isThenable(value: mixed): boolean {
   return (
     value != null &&
     (typeof value === "object" || typeof value === "function") &&
-    typeof (value: $FlowFixMe).then === "function"
+    typeof (value as $FlowFixMe).then === "function"
   );
 }
 
@@ -314,7 +314,7 @@ function exportsOf(specifier: string, produced: mixed): { [string]: mixed } {
         `object, and it returned ${produced === null ? "null" : typeof produced}`,
     );
   }
-  return { ...(produced: $FlowFixMe) };
+  return { ...(produced as $FlowFixMe) };
 }
 
 /**
@@ -344,10 +344,10 @@ function automock(value: mixed, depth: number, seen: Map<mixed, mixed>): mixed {
   }
 
   if (typeof value === "function") {
-    const spy = fn().mockName((value: $FlowFixMe).name ?? "spy");
+    const spy = fn().mockName((value as $FlowFixMe).name ?? "spy");
     seen.set(value, spy);
     copyProperties(value, spy, depth, seen, false);
-    const prototype = (value: $FlowFixMe).prototype;
+    const prototype = (value as $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
@@ -390,8 +390,8 @@ function copyProperties(
   seen: Map<mixed, mixed>,
   hidden: boolean,
 ): void {
-  const source = (from: $FlowFixMe);
-  const target = (onto: $FlowFixMe);
+  const source = from as $FlowFixMe;
+  const target = onto as $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,
@@ -426,5 +426,5 @@ function isPlainish(value: mixed): boolean {
 
 /** Whether `value` is a module namespace object. */
 function isNamespace(value: mixed): boolean {
-  return (value: $FlowFixMe)[Symbol.toStringTag] === "Module";
+  return (value as $FlowFixMe)[Symbol.toStringTag] === "Module";
 }

package/internal/namespace.js

@@ -160,17 +160,22 @@ export async function waitFor<T>(
   const deadline = Date.now() + timeout;
   let last: mixed = null;
 
-  for (;;) {
+  // Ends when the deadline passes; the `throw` after it is the only way out
+  // that is not a result. A condition rather than `for (;;)`, because Flow does
+  // not treat an infinite loop as ending the function (facebook/flow#7657).
+  let expired = false;
+  while (!expired) {
     try {
       return await body();
     } catch (thrown) {
       last = thrown;
     }
-    if (Date.now() >= deadline) {
-      throw last ?? new Error(`uft.waitFor: gave up after ${timeout}ms`);
+    expired = Date.now() >= deadline;
+    if (!expired) {
+      await new Promise((resolve) => setTimeout(resolve, interval));
     }
-    await new Promise((resolve) => setTimeout(resolve, interval));
   }
+  throw last ?? new Error(`uft.waitFor: gave up after ${timeout}ms`);
 }
 
 /** Run `body` until it returns something truthy, or the timeout passes. */

package/internal/registry.js

@@ -19,7 +19,7 @@
 // * `.only` anywhere in the file restricts the file to marked cases and their
 //   ancestors; everything else is reported skipped, never silently dropped.
 
-import { firstUserSite } from "./frames.js";
+import { callerSite, firstUserSite } from "./frames.js";
 
 /** The placeholders `it.each` substitutes a row into. */
 const ROW_TOKEN = /%[sjdi]/g;
@@ -27,6 +27,16 @@ const ROW_TOKEN = /%[sjdi]/g;
 /** What a test or hook body may return. */
 export type Body = () => mixed | Promise<mixed>;
 
+/**
+ * One `beforeAll`, `afterAll`, `beforeEach` or `afterEach`.
+ *
+ * `timeoutMs` is the hook's own budget when its registration named one, and
+ * `null` when the hook runs under the budget of the case it belongs to. A hook
+ * that starts a process or a server needs longer than the cases it sets up for,
+ * and without a budget of its own the only lever was the file-wide timeout.
+ */
+export type Hook = {| readonly body: Body, readonly timeoutMs: number | null |};
+
 /** The suffix written on a registration call. */
 export type Modifier = "none" | "only" | "skip" | "todo";
 
@@ -63,10 +73,10 @@ export type Suite = {|
   readonly name: string,
   readonly modifier: Modifier,
   readonly children: Array<Suite | Case>,
-  readonly beforeAll: Array<Body>,
-  readonly afterAll: Array<Body>,
-  readonly beforeEach: Array<Body>,
-  readonly afterEach: Array<Body>,
+  readonly beforeAll: Array<Hook>,
+  readonly afterAll: Array<Hook>,
+  readonly beforeEach: Array<Hook>,
+  readonly afterEach: Array<Hook>,
   readonly line: number,
   readonly column: number,
 |};
@@ -118,6 +128,10 @@ export function collected(): Suite {
  * treats as "unknown" rather than as line one.
  */
 function callSite(): {| readonly line: number, readonly column: number |} {
+  const site = callerSite(callSite);
+  if (site !== undefined) {
+    return site ?? { line: 0, column: 0 };
+  }
   return firstUserSite(new Error("position").stack) ?? { line: 0, column: 0 };
 }
 
@@ -276,22 +290,42 @@ function formatRow(name: string, row: mixed): string {
   });
 }
 
-/** Run once before the first test in this suite that runs. */
-export function beforeAll(body: Body): void {
-  current.beforeAll.push(body);
+/**
+ * A hook's own budget, from the second argument of its registration.
+ *
+ * `{ timeout }` is what `it` takes, and a bare number is what Jest and Vitest
+ * take — a suite moved from either writes `beforeAll(start, 30_000)`, and a
+ * budget that was silently dropped would fail as a timeout the file never
+ * asked for.
+ */
+function hookTimeout(options: ?(TestOptions | number)): number | null {
+  if (typeof options === "number") {
+    return options;
+  }
+  return options?.timeout ?? null;
+}
+
+/**
+ * Run once before the first test in this suite that runs.
+ *
+ * When it fails, every case it was setting up for fails with its error: none
+ * of them runs against a setup that did not happen.
+ */
+export function beforeAll(body: Body, options?: TestOptions | number): void {
+  current.beforeAll.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run once after the last test in this suite that ran. */
-export function afterAll(body: Body): void {
-  current.afterAll.push(body);
+export function afterAll(body: Body, options?: TestOptions | number): void {
+  current.afterAll.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run before every test in this suite and its children. */
-export function beforeEach(body: Body): void {
-  current.beforeEach.push(body);
+export function beforeEach(body: Body, options?: TestOptions | number): void {
+  current.beforeEach.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run after every test in this suite and its children, including failures. */
-export function afterEach(body: Body): void {
-  current.afterEach.push(body);
+export function afterEach(body: Body, options?: TestOptions | number): void {
+  current.afterEach.push({ body, timeoutMs: hookTimeout(options) });
 }

package/internal/run.js

@@ -13,7 +13,14 @@ import * as output from "./output.js";
 import * as snapshot from "./snapshot.js";
 import { AssertionError } from "./expect.js";
 import { type Site, firstUserSite, siteInFile, userFrames } from "./frames.js";
-import { type BenchOptions, type Body, type Case, type Suite, collected } from "./registry.js";
+import {
+  type BenchOptions,
+  type Body,
+  type Case,
+  type Hook,
+  type Suite,
+  collected,
+} from "./registry.js";
 
 /** How one case ended. */
 export type Outcome =
@@ -186,8 +193,8 @@ function failure(thrown: mixed, file: string | null): Outcome {
 /** Everything one case needs from the suites above it. */
 type Context = {|
   readonly path: $ReadOnlyArray<string>,
-  readonly beforeEach: $ReadOnlyArray<Body>,
-  readonly afterEach: $ReadOnlyArray<Body>,
+  readonly beforeEach: $ReadOnlyArray<Hook>,
+  readonly afterEach: $ReadOnlyArray<Hook>,
   readonly skipped: boolean,
   readonly onlyPath: boolean,
 |};
@@ -268,7 +275,7 @@ async function runCase(
   await output.runInTest(name, async () => {
     try {
       for (const hook of context.beforeEach) {
-        await withTimeout(hook, timeoutMs);
+        await withTimeout(hook.body, hook.timeoutMs ?? timeoutMs);
       }
       if (benchmark) {
         samples = await measure(body, test.bench, timeoutMs);
@@ -282,7 +289,7 @@ async function runCase(
     // when the body had not already failed.
     for (const hook of context.afterEach) {
       try {
-        await withTimeout(hook, timeoutMs);
+        await withTimeout(hook.body, hook.timeoutMs ?? timeoutMs);
       } catch (thrown) {
         if (outcome.status === "passed") {
           outcome = failure(thrown, options.file ?? null);
@@ -396,16 +403,25 @@ async function runSuite(
   // every `beforeAll` in an ordinary file — one where the tests live inside a
   // `describe` — never running at all, silently. The chain is walked outermost
   // first, so an inner suite's setup sees what the outer one did.
+  //
+  // Once, and remembered either way. The outcome is kept rather than a "done"
+  // flag, because a flag raised before the hooks ran let every case after the
+  // first go ahead when setup had failed: the first case reported the hook's
+  // error and the rest ran against a fixture that was never made, failing — or
+  // worse, passing — for reasons that had nothing to do with them.
   let setUp = false;
-  const setUpOnce = async () => {
-    if (setUp) {
-      return;
-    }
-    await setUpAncestors();
-    setUp = true;
-    for (const hook of node.beforeAll) {
-      await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  let setup: Promise<void> | null = null;
+  const setUpOnce = (): Promise<void> => {
+    if (setup == null) {
+      setUp = true;
+      setup = (async () => {
+        await setUpAncestors();
+        for (const hook of node.beforeAll) {
+          await withTimeout(hook.body, hook.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        }
+      })();
     }
+    return setup;
   };
 
   let passed = true;
@@ -455,7 +471,7 @@ async function runSuite(
   if (setUp) {
     for (const hook of node.afterAll) {
       try {
-        await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        await withTimeout(hook.body, hook.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
       } catch {
         // A teardown failure cannot fail a test that already reported, and
         // there is nothing left to attach it to; the file's own status carries

package/internal/snapshot.js

@@ -56,7 +56,7 @@ const loaded: Map<string, { entries: { [string]: string }, dirty: boolean }> = n
 
 /** Whether this run may rewrite a snapshot that did not match. */
 function updating(): boolean {
-  const value = (globalThis: $FlowFixMe).process?.env?.UF_UPDATE_SNAPSHOTS;
+  const value = (globalThis as $FlowFixMe).process?.env?.UF_UPDATE_SNAPSHOTS;
   return value != null && value !== "" && value !== "0";
 }
 
@@ -101,7 +101,7 @@ function entriesFor(file: string): { entries: { [string]: string }, dirty: boole
     return already;
   }
 
-  const state = { entries: (Object.create(null): $FlowFixMe), dirty: false };
+  const state = { entries: Object.create(null) as $FlowFixMe, dirty: false };
   if (existsSync(target)) {
     parseInto(readFileSync(target, "utf8"), state.entries);
   }

package/internal/spy.js

@@ -3,9 +3,27 @@
 // Internal to `@uniflowed/test`: the spy behind `fn` and `uft.spyOn`.
 //
 // Shaped after Vitest's, because a project moving to uf should not have to
-// rewrite its assertions. That means `mock.calls`, `mock.results`,
-// `mock.lastCall`, the `Once` variants, and `mockReset` and `mockRestore`
-// meaning the two different things they mean there.
+// rewrite its assertions. That means `mock` holds exactly what Vitest's does,
+// in the same shapes:
+//
+// * `calls` — one array of arguments per call, so `mock.calls[0][0]` is the
+//   first call's first argument and `mock.calls.map((args) => args[0])` works
+//   as it does there. It used to hold `{ args, returned }` objects, which read
+//   well and broke every assertion carried over from Vitest or Jest.
+// * `results` — `{ type, value }` per call: `"return"` or `"throw"`, and
+//   `"incomplete"` while the call has not returned yet (a spy asked about
+//   itself from inside its own implementation).
+// * `settledResults` — `{ type, value }` per call once the value settled:
+//   `"fulfilled"` or `"rejected"` for a promise, `"fulfilled"` at once for
+//   anything else, `"incomplete"` until then.
+// * `contexts` — the `this` of each call; `instances` — the same, except that
+//   a call made with `new` records the instance it constructed, in both.
+// * `invocationCallOrder` — a number per call, counted across every spy in the
+//   process, so two spies can say which was called first.
+// * `lastCall` — the last call's arguments, or `undefined` before any.
+//
+// And the `Once` variants, and `mockReset` and `mockRestore` meaning the two
+// different things they mean there.
 //
 // The three reset verbs are easy to conflate and are genuinely different:
 //
@@ -18,17 +36,35 @@
 // Every spy is registered, so `uft.clearAllMocks` and its siblings can reach the
 // ones a test never held a reference to.
 
-/** One call: what went in, and what came out. */
-export type SpyCall = {
-  readonly args: $ReadOnlyArray<mixed>,
-  readonly returned?: mixed,
-  readonly threw?: mixed,
-};
+/** One call's arguments, as Vitest's `mock.calls` holds them. */
+export type SpyCall = $ReadOnlyArray<mixed>;
 
-/** One call's outcome, in the shape Vitest reports it. */
+/**
+ * One call's outcome, in the shape Vitest reports it.
+ *
+ * `"incomplete"` is a call that has not returned yet — only ever seen from
+ * inside the call itself — and its `value` is `undefined`.
+ */
 export type SpyResult =
   | { readonly type: "return", readonly value: mixed }
-  | { readonly type: "throw", readonly value: mixed };
+  | { readonly type: "throw", readonly value: mixed }
+  | { readonly type: "incomplete", readonly value: void };
+
+/**
+ * One call's value once it settled, in the shape Vitest reports it.
+ *
+ * A promise settles when it does; anything else settles as the call returns.
+ */
+export type SpySettledResult =
+  | { readonly type: "fulfilled", readonly value: mixed }
+  | { readonly type: "rejected", readonly value: mixed }
+  | { readonly type: "incomplete", readonly value: void };
+
+/**
+ * The order calls happened in, across every spy in the process: Vitest's
+ * `invocationCallOrder`, which starts at one.
+ */
+let invocations = 0;
 
 /** Every spy made in this process, so the `All` verbs can reach them. */
 const registry: Array<$FlowFixMe> = [];
@@ -44,8 +80,11 @@ type Restore = null | (() => void);
  */
 function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFixMe {
   const calls: Array<SpyCall> = [];
-  const results: Array<SpyResult> = [];
+  const results: Array<$FlowFixMe> = [];
+  const settledResults: Array<$FlowFixMe> = [];
+  const contexts: Array<mixed> = [];
   const instances: Array<mixed> = [];
+  const invocationCallOrder: Array<number> = [];
   // Implementations queued by the `Once` variants, taken from the front.
   const queued: Array<mixed> = [];
 
@@ -53,36 +92,84 @@ function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFi
   let current = implementation;
   let mockName = name;
 
-  const spy: $FlowFixMe = function (...args: $ReadOnlyArray<mixed>) {
+  const spy: $FlowFixMe = function (this: mixed, ...args: $ReadOnlyArray<mixed>) {
+    // Recorded before the implementation runs, as Vitest records it, so a spy
+    // that asks about itself from inside its own call sees that call already.
+    calls.push(args);
+    invocations += 1;
+    invocationCallOrder.push(invocations);
+    const result: $FlowFixMe = { type: "incomplete", value: undefined };
+    const settled: $FlowFixMe = { type: "incomplete", value: undefined };
+    results.push(result);
+    settledResults.push(settled);
     // `this` is recorded because a spy on a method is often called as one, and
-    // `mock.instances` is how a test asserts on the receiver.
-    instances.push(this);
+    // `mock.contexts` is how a test asserts on the receiver. A construction has
+    // no receiver yet; the instance it makes is recorded once there is one.
+    const constructing = new.target !== undefined;
+    const context = constructing ? undefined : this;
+    const at = contexts.push(context) - 1;
+    instances.push(context);
     const body = queued.length > 0 ? queued.shift() : current;
+    let returned;
     try {
-      const returned = typeof body === "function" ? body.apply(this, args) : undefined;
-      calls.push({ args, returned });
-      results.push({ type: "return", value: returned });
-      return returned;
+      if (constructing) {
+        returned =
+          typeof body === "function"
+            ? Reflect.construct(body as $FlowFixMe, [...args], new.target)
+            : this;
+      } else {
+        returned = typeof body === "function" ? body.apply(this, args) : undefined;
+      }
     } catch (thrown) {
-      calls.push({ args, threw: thrown });
-      results.push({ type: "throw", value: thrown });
+      result.type = "throw";
+      result.value = thrown;
+      settled.type = "rejected";
+      settled.value = thrown;
       throw thrown;
     }
+    result.type = "return";
+    result.value = returned;
+    if (constructing) {
+      contexts[at] = returned;
+      instances[at] = returned;
+    }
+    if (returned instanceof Promise) {
+      returned.then(
+        (value) => {
+          settled.type = "fulfilled";
+          settled.value = value;
+        },
+        (reason) => {
+          settled.type = "rejected";
+          settled.value = reason;
+        },
+      );
+    } else {
+      settled.type = "fulfilled";
+      settled.value = returned;
+    }
+    return returned;
   };
 
   spy.mock = {
     calls,
     results,
+    settledResults,
+    contexts,
     instances,
-    get lastCall(): $ReadOnlyArray<mixed> | void {
-      return calls.length === 0 ? undefined : calls[calls.length - 1].args;
+    invocationCallOrder,
+    get lastCall(): SpyCall | void {
+      return calls.length === 0 ? undefined : calls[calls.length - 1];
     },
   };
 
   spy.mockClear = () => {
     calls.length = 0;
     results.length = 0;
+    settledResults.length = 0;
+    contexts.length = 0;
     instances.length = 0;
+    invocationCallOrder.length = 0;
     return spy;
   };
   spy.mockReset = () => {
@@ -114,8 +201,8 @@ function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFi
       const out = body();
       // An async body has to put the implementation back when it settles, not
       // when it starts, or the next test runs against this one's stand-in.
-      if (out != null && typeof (out: $FlowFixMe).then === "function") {
-        return (out: $FlowFixMe).finally(() => {
+      if (out != null && typeof (out as $FlowFixMe).then === "function") {
+        return (out as $FlowFixMe).finally(() => {
           current = previous;
         });
       }
@@ -136,7 +223,7 @@ function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFi
   spy.mockRejectedValueOnce = (reason: mixed) =>
     spy.mockImplementationOnce(() => Promise.reject(reason));
   spy.mockReturnThis = () =>
-    spy.mockImplementation(function () {
+    spy.mockImplementation(function (this: mixed) {
       return this;
     });
 
@@ -203,7 +290,7 @@ export function spyOn(object: mixed, method: string): $FlowFixMe {
 
 /** Whether `value` is one of these spies. */
 export function isSpy(value: mixed): boolean {
-  return typeof value === "function" && (value: $FlowFixMe).mock != null;
+  return typeof value === "function" && (value as $FlowFixMe).mock != null;
 }
 
 /** Forget every spy's calls, keeping their implementations. */

package/internal/timers.js

@@ -87,7 +87,9 @@ export function installFakeClock(): void {
     return;
   }
   const global = host();
-  installed = {
+  // Kept in a local as well as the module's `installed`: the calls below would
+  // otherwise make Flow forget that `installed` was just set.
+  const saved = {
     setTimeout: global.setTimeout,
     clearTimeout: global.clearTimeout,
     setInterval: global.setInterval,
@@ -96,6 +98,7 @@ export function installFakeClock(): void {
     clearImmediate: global.clearImmediate,
     Date: global.Date,
   };
+  installed = saved;
 
   now = Date.now();
   tasks = [];
@@ -116,22 +119,23 @@ export function installFakeClock(): void {
   global.clearTimeout = cancel;
   global.clearInterval = cancel;
   global.clearImmediate = cancel;
-  global.Date = fakeDate(installed.Date as $FlowFixMe);
+  global.Date = fakeDate(saved.Date as $FlowFixMe);
 }
 
 /** Put the real scheduling globals back. */
 export function restoreRealClock(): void {
-  if (installed == null) {
+  const saved = installed;
+  if (saved == null) {
     return;
   }
   const global = host();
-  global.setTimeout = installed.setTimeout;
-  global.clearTimeout = installed.clearTimeout;
-  global.setInterval = installed.setInterval;
-  global.clearInterval = installed.clearInterval;
-  global.setImmediate = installed.setImmediate;
-  global.clearImmediate = installed.clearImmediate;
-  global.Date = installed.Date;
+  global.setTimeout = saved.setTimeout;
+  global.clearTimeout = saved.clearTimeout;
+  global.setInterval = saved.setInterval;
+  global.clearInterval = saved.clearInterval;
+  global.setImmediate = saved.setImmediate;
+  global.clearImmediate = saved.clearImmediate;
+  global.Date = saved.Date;
   installed = null;
   tasks = [];
 }
@@ -167,7 +171,7 @@ function fakeDate(Real: $FlowFixMe): $FlowFixMe {
     construct(target: $FlowFixMe, args: $ReadOnlyArray<mixed>, newTarget: $FlowFixMe) {
       // Only the no-argument form reads the clock; every other form is
       // constructing a specific date and has nothing to do with "now".
-      const actual = args.length === 0 ? [now] : args;
+      const actual: Array<mixed> = args.length === 0 ? [now] : [...args];
       // `newTarget` rather than `Real`, so a subclass of the faked `Date` gets
       // its own prototype instead of the real one's.
       return Reflect.construct(Real, actual, newTarget === undefined ? Real : newTarget);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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",
@@ -38,7 +38,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.1.0",
+    "@uniflowed/host": "0.3.0",
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"
   },

package/worker.js

@@ -54,6 +54,9 @@ import { writeChangedSnapshots } from "./internal/snapshot.js";
 import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import fs from "node:fs";
+import path from "node:path";
+
 import { installInSourceTests } from "./in-source.js";
 import { restoreSharedState } from "./internal/isolation.js";
 import { run } from "./internal/run.js";
@@ -72,9 +75,16 @@ import { run } from "./internal/run.js";
 // has the global like Node and Bun. A shim for a host uf no longer starts would
 // be a line claiming to be load-bearing while holding nothing up.
 
-/** What `uf` sends for one file. */
+/** What `uf` sends for one file, or to say which files changed. */
 type Request = {|
-  readonly file: string,
+  readonly file?: string,
+  /**
+   * Files that changed since this worker last ran one, as absolute paths.
+   *
+   * Sent on its own, between runs, to a `uf test --watch` worker that is kept
+   * for the next run; see [`invalidate`].
+   */
+  readonly invalidate?: $ReadOnlyArray<string>,
   readonly filter?: string | null,
   readonly timeoutMs?: number,
   /**
@@ -86,6 +96,12 @@ type Request = {|
   readonly generation?: number,
 |};
 
+/** A request that names a file, which is every request but an invalidation. */
+type FileRequest = {|
+  ...Request,
+  readonly file: string,
+|};
+
 /**
  * The request whose work the code running right now descends from.
  *
@@ -159,11 +175,11 @@ function write(event: { readonly [string]: mixed }): void {
  * run, set once on the worker by `uf`, and not something each request says.
  */
 function benching(): boolean {
-  const value = (globalThis: $FlowFixMe).process?.env?.UF_TEST_BENCH;
+  const value = (globalThis as $FlowFixMe).process?.env?.UF_TEST_BENCH;
   return value != null && value !== "" && value !== "0";
 }
 
-async function runFile(request: Request, generation: number): Promise<void> {
+async function runFile(request: FileRequest, generation: number): Promise<void> {
   const started = performance.now();
   // Everything the previous file changed and this package shares with it goes
   // back: the registry, the stubbed environment and globals, the clock, the
@@ -213,7 +229,7 @@ async function runFile(request: Request, generation: number): Promise<void> {
  * either of the two `return`s below escaping it.
  */
 async function runImportedFile(
-  request: Request,
+  request: FileRequest,
   generation: number,
   url: string,
   started: number,
@@ -285,6 +301,25 @@ async function runImportedFile(
   }
 }
 
+/**
+ * Load the modules `changed` reaches afresh from the next import on.
+ *
+ * A `uf test --watch` worker is kept between runs, and an edit has to reach
+ * it: the changed files, and every module this process loaded that imports
+ * one, are given a new URL by `@uniflowed/host`'s resolve hook, so the next
+ * file imports them as they are on disk now and shares everything else, as a
+ * worker's files always have. `false` when that cannot be promised — no such
+ * hook in this process, or an edit that reaches a module `require()` loaded —
+ * and `uf` then runs the next file in a fresh worker instead.
+ */
+function invalidate(changed: $ReadOnlyArray<string>): boolean {
+  const epochs = (globalThis as $FlowFixMe)[Symbol.for("@uniflowed/host/module-epochs")];
+  if (epochs == null || typeof epochs.invalidate !== "function") {
+    return false;
+  }
+  return epochs.invalidate(changed) === true;
+}
+
 /**
  * Serve requests until stdin closes.
  *
@@ -321,13 +356,24 @@ function serve(): void {
       return;
     }
     served += 1;
+    if (request.file == null) {
+      const at = request.generation ?? served;
+      const changed = request.invalidate ?? [];
+      queue = queue.then(() =>
+        serving.run(at, () => {
+          write({ event: "invalidated", ok: invalidate(changed) });
+        }),
+      );
+      return;
+    }
+    const file = request.file;
     // `uf` chooses the number, because `uf` is the side that checks it. This
     // count of served requests is the same sequence and stands in for a `uf`
     // too old to send one — without something monotonic here the import below
     // would be cache-busted with `undefined` and a watch-mode rerun would see
     // the module it already had.
     const at = request.generation ?? served;
-    queue = queue.then(() => serving.run(at, () => runFile(request, at)));
+    queue = queue.then(() => serving.run(at, () => runFile({ ...request, file }, at)));
   });
 
   process.stdin.on("close", () => {
@@ -355,4 +401,65 @@ process.on("unhandledRejection", (reason: mixed) => {
   process.exit(1);
 });
 
+// The same for an exception nothing caught — a server's `error` event with no
+// listener, a throw from a timer callback. Node's default prints the stack to
+// stderr and exits, and all `uf` could then say was that the worker had died:
+// the file that did it went unnamed, and the message was somewhere above the
+// report, unattributed. Reported the way a rejection is, it is the failure of
+// the file whose work threw, with its message and stack in the file's result.
+process.on("uncaughtException", (thrown: mixed) => {
+  const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+  write({
+    event: "file",
+    status: "run-failed",
+    message: `uncaught exception: ${error.message}`,
+    stack: error.stack ?? null,
+  });
+  process.exit(1);
+});
+
+/**
+ * Give every test file its own copy of the project's modules.
+ *
+ * The Flow loader in `@uniflowed/host` imports every project module a test
+ * file reaches under a URL that names the file's run, so no module-level state
+ * — a React context's current value, a cache, a registry a package keeps —
+ * outlives the file that set it (ubugeeei-prod/uf#1443). Installed packages
+ * and the runner itself stay one instance per process; `internal/file-scope.js`
+ * in `@uniflowed/host` says why each is on its side of the line.
+ *
+ * The runner is named by directory: this package's and the loader's, as the
+ * loader will see them — real paths, because a workspace reaches both through
+ * a `node_modules` symlink and the loader is handed where they really are.
+ */
+function scopeModulesToFiles(): void {
+  const here = path.dirname(fileURLToPath(String(import.meta.url)));
+  let host: string | null = null;
+  try {
+    host = path.dirname(
+      fileURLToPath(String((import.meta as $FlowFixMe).resolve("@uniflowed/host/register"))),
+    );
+  } catch {
+    // A host without `import.meta.resolve`: the loader's own modules are
+    // reached from this package's, never from a test file's, so leaving them
+    // out of the list only matters for a test that imports the loader itself.
+  }
+  const shared = [here, host]
+    .filter((directory) => directory != null)
+    .map((directory) => {
+      try {
+        return fs.realpathSync(String(directory));
+      } catch {
+        return String(directory);
+      }
+    });
+  Object.defineProperty(globalThis, Symbol.for("@uniflowed/host/file-scope"), {
+    value: Object.freeze({ shared: Object.freeze(shared) }),
+    configurable: true,
+    enumerable: false,
+    writable: false,
+  });
+}
+
+scopeModulesToFiles();
 serve();