@uniflowed/test 0.2.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,

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/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.2.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.2.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", () => {
@@ -372,4 +418,48 @@ process.on("uncaughtException", (thrown: mixed) => {
   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();