@uniflowed/test 0.0.0-alpha.13 → 0.0.0-alpha.15

package/internal/expect.js

@@ -289,29 +289,36 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
  * Every entry returns a [`Verdict`] rather than throwing, which is what lets
  * `.not` reuse all of them.
  *
- * # The `any` in the indexer
+ * # Every entry takes `mixed`, and that is what makes the indexer sayable
  *
- * The entries do not agree about their arguments — `toBe` takes a `mixed`,
- * `toHaveLength` takes a `number`, `toBeCloseTo` takes two — and [`bind`]
- * applies whichever one it was asked for to a `$ReadOnlyArray<mixed>` it
- * collected from a caller. Parameters are contravariant, so one indexer cannot
- * describe both ends: `(...args: $ReadOnlyArray<mixed>)` rejects every entry
- * that wants a `number`, and `(...args: $ReadOnlyArray<empty>)` accepts every
- * entry and rejects the call.
+ * [`bind`] reaches an entry by a computed key and applies it to the
+ * `$ReadOnlyArray<mixed>` it collected from the caller, so the indexer has to
+ * describe a function that will accept those arguments. Parameters are
+ * contravariant, so an entry that demanded a `number` could not be described
+ * by one — `(...args: $ReadOnlyArray<mixed>)` rejects it, and
+ * `(...args: $ReadOnlyArray<empty>)` accepts it and rejects the call. That
+ * disagreement is why this indexer used to be written `$ReadOnlyArray<any>`,
+ * with a `flow/unclear-type` suppression on it.
  *
- * That is unchanged, and it is now the last of it. Where a caller used to meet
- * this indexer through an unbroken chain of `$FlowFixMe`, the published
- * surface is [`Expectation`] and the disagreement the indexer papers over is
- * written down there, one signature per name. What survives is a table reached
- * by a computed key inside this module, between `verdicts` and `bind` — two
- * functions in one file, neither of which a consumer can see — and narrowing
- * it means writing `bind`'s forty-one wrappers out by hand to avoid the
- * lookup. That is a second copy of the listing to keep in step with this one,
- * which is a worse trade than the suppression it removes.
+ * So the disagreement is gone instead of papered over: every entry here takes
+ * `mixed` and coerces what it needs, the way most of them — `toBe`,
+ * `toBeGreaterThan`, `toHaveAttribute` — already did. Nothing a caller can see
+ * got wider: `toHaveLength` still refuses a string and `toBeTypeOf` still
+ * refuses a word `typeof` never says, because those are [`Matchers`]'s
+ * signatures and [`Matchers`] is the published type. What changed is that the
+ * table behind them stopped claiming a narrower argument than the one `bind`
+ * can hand it, which is a claim that was never true. The `String(…)` and
+ * `Number(…)` calls that appeared with it are the coercion the runtime was
+ * already doing, said out loud, and each produces the same message the implicit
+ * one did for the same input.
+ *
+ * The alternative — narrowing the indexer by writing `bind`'s forty-one
+ * wrappers out to avoid the computed lookup — is a second copy of the listing
+ * to keep in step with [`Matchers`], and is a worse trade than either. See
+ * ubugeeei-prod/uf#402.
  */
 function verdicts(received: mixed): {
-  // uf-lint-disable-next-line flow/unclear-type
-  readonly [string]: (...args: $ReadOnlyArray<any>) => Verdict,
+  readonly [string]: (...args: $ReadOnlyArray<mixed>) => Verdict,
 } {
   const shown = () => render(received);
   const simple = (pass: boolean, what: string, expected?: mixed): Verdict => ({
@@ -386,14 +393,15 @@ function verdicts(received: mixed): {
         `to be at most ${render(expected)}`,
         expected,
       ),
-    toBeCloseTo: (expected: number, digits?: number) => {
-      const places = digits ?? 2;
+    toBeCloseTo: (expected: mixed, digits?: mixed) => {
+      const target = Number(expected);
+      const places = digits === undefined ? 2 : Number(digits);
       const tolerance = 10 ** -places / 2;
-      const difference = Math.abs((received as $FlowFixMe) - expected);
+      const difference = Math.abs((received as $FlowFixMe) - target);
       return simple(
         difference < tolerance,
-        `to be within ${tolerance} of ${expected}, but it is off by ${difference}`,
-        expected,
+        `to be within ${tolerance} of ${target}, but it is off by ${difference}`,
+        target,
       );
     },
     toContain: (expected: mixed) => {
@@ -419,22 +427,23 @@ function verdicts(received: mixed): {
         expected,
       );
     },
-    toHaveLength: (expected: number) => {
+    toHaveLength: (expected: mixed) => {
       const length = received == null ? undefined : (received as $FlowFixMe).length;
       return simple(
         length === expected,
-        `to have length ${expected}, not ${render(length)}`,
+        `to have length ${String(expected)}, not ${render(length)}`,
         expected,
       );
     },
-    toHaveProperty: (path: string, ...rest: $ReadOnlyArray<mixed>) => {
-      const found = propertyAt(received, path);
+    toHaveProperty: (path: mixed, ...rest: $ReadOnlyArray<mixed>) => {
+      const at = String(path);
+      const found = propertyAt(received, at);
       if (rest.length === 0) {
-        return simple(found.found, `to have a property at \`${path}\``);
+        return simple(found.found, `to have a property at \`${at}\``);
       }
       return simple(
         found.found && equals(found.value, rest[0]),
-        `to have \`${path}\` equal to ${render(rest[0])}, not ${render(found.value)}`,
+        `to have \`${at}\` equal to ${render(rest[0])}, not ${render(found.value)}`,
         rest[0],
       );
     },
@@ -454,16 +463,24 @@ function verdicts(received: mixed): {
         `to be an instance of ${render(expected)}`,
         expected,
       ),
-    toBeTypeOf: (expected: string) =>
+    toBeTypeOf: (expected: mixed) => {
+      const name = String(expected);
+      return simple(
+        typeof received === name,
+        `to be of type ${name}, not ${typeof received}`,
+        name,
+      );
+    },
+    toSatisfy: (predicate: mixed) =>
       simple(
-        typeof received === expected,
-        `to be of type ${expected}, not ${typeof received}`,
-        expected,
+        typeof predicate === "function" && predicate(received) === true,
+        "to satisfy the predicate",
       ),
-    toSatisfy: (predicate: (value: mixed) => boolean) =>
-      simple(predicate(received) === true, "to satisfy the predicate"),
-    toMatchSnapshot: (hint?: string): Verdict => {
-      const verdict = snapshot.matchSnapshot(received, hint);
+    toMatchSnapshot: (hint?: mixed): Verdict => {
+      const verdict = snapshot.matchSnapshot(
+        received,
+        hint === undefined ? undefined : String(hint),
+      );
       return {
         pass: verdict.pass,
         expected: verdict.expected ?? "(no snapshot yet)",
@@ -477,8 +494,11 @@ function verdicts(received: mixed): {
         negatedFailure: () => "expected the value not to match its snapshot",
       };
     },
-    toMatchInlineSnapshot: (expected?: string): Verdict => {
-      const verdict = snapshot.matchInlineSnapshot(received, expected);
+    toMatchInlineSnapshot: (expected?: mixed): Verdict => {
+      const verdict = snapshot.matchInlineSnapshot(
+        received,
+        expected === undefined ? undefined : String(expected),
+      );
       return {
         pass: verdict.pass,
         expected: verdict.expected ?? "(no inline snapshot yet)",
@@ -529,10 +549,14 @@ function verdicts(received: mixed): {
       requireSpy("toHaveBeenCalled");
       return simple(spyCalls().length > 0, "to have been called");
     },
-    toHaveBeenCalledTimes: (count: number) => {
+    toHaveBeenCalledTimes: (count: mixed) => {
       requireSpy("toHaveBeenCalledTimes");
       const actual = spyCalls().length;
-      return simple(actual === count, `to have been called ${count} times, not ${actual}`, count);
+      return simple(
+        actual === count,
+        `to have been called ${String(count)} times, not ${actual}`,
+        count,
+      );
     },
     toHaveBeenCalledWith: (...args: $ReadOnlyArray<mixed>) => {
       requireSpy("toHaveBeenCalledWith");

package/internal/isolation.js

@@ -0,0 +1,200 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: what a file is allowed to leave behind.
+//
+// A worker serves many files out of one process, one at a time (`../worker.js`
+// says why). Everything a file registers lives in this package and is cleared
+// with it; everything a file *reaches around* the package to change belongs to
+// the process, outlives the file, and is handed to whichever file the schedule
+// puts next in that worker.
+//
+// That second list is what this module is. It has been discovered three times,
+// once per entry, and each time the same way — a suite that passed alone and
+// failed beside another, naming the file that read the value rather than the
+// file that wrote it:
+//
+//   * ubugeeei-prod/uf#417, `uft.stubEnv("NODE_ENV", …)` still set for the
+//     next file;
+//   * ubugeeei-prod/uf#581, a fake clock still installed, so the next file's
+//     `setTimeout` — including the one each case is raced against — never
+//     fired and the file hung with nothing on screen;
+//   * ubugeeei-prod/uf#607, `document.body` still holding the markup a
+//     hydration test wrote into it, so the next file's "there is one image on
+//     the page" found six.
+//
+// Which files share a worker is decided by `.uf/test-timings.json`, so a leak
+// makes the *result* of a suite depend on how the machine was loaded the last
+// time it ran. That is the failure this module exists to end, and the reason
+// it is a list in one place rather than three calls in `../worker.js`: the
+// question "what else does a file share with the next one" now has somewhere
+// to be answered, and a fourth answer is one entry rather than one more thing
+// to remember.
+//
+// # What belongs here
+//
+// State that (a) the process shares, (b) a test can change from inside a file,
+// and (c) nothing else puts back. Anything a file merely *reads* does not
+// belong here, and neither does anything the registry already clears — a spy
+// is not on this list because `reset()` is what a spy lives in.
+//
+// # When it runs
+//
+// Before the next file is imported, not after the previous one is run. A file
+// that throws while loading is still a file that has run code, and it still
+// hands the next one whatever that code changed; putting things back on the
+// way *in* covers the load failure and the crash as well as the ordinary end.
+// It also means the first file in a worker starts from the same state as the
+// tenth.
+
+import { reset } from "./registry.js";
+import { resetModuleState } from "./modules.js";
+import { unstubAllEnvs, unstubAllGlobals } from "./namespace.js";
+// Renamed at the door, for two reasons that agree. It reads as the resets
+// beside it do — `reset`, `unstubAllEnvs`, `resetModuleState` are all
+// verb-first, and so is what this does to the clock. And `useRealTimers` is
+// not a React hook: it is uf's own timer control, which happens to be named
+// the way every runner names it, and calling it bare in a plain function is a
+// `react/hooks-rules` error on the name alone. A suppression would assert
+// something about this call; the name is simply accurate.
+import { useRealTimers as restoreRealClock } from "./timers.js";
+
+/**
+ * One piece of process-wide state a file can change, and how to put it back.
+ *
+ * `what` is written for a person reading this list rather than for any code:
+ * nothing branches on it, and it is here because a list of five bare function
+ * references is a list nobody can check against the paragraph above it.
+ */
+type Shared = {|
+  readonly what: string,
+  readonly restore: () => void,
+|};
+
+/**
+ * Everything a file shares with the file after it, in the order it goes back.
+ *
+ * The order matters in one place and is harmless everywhere else: the clock
+ * goes back before the module stand-ins do, because a stand-in's factory runs
+ * on the next import and a factory that schedules anything under a leaked fake
+ * clock would schedule it into a clock nobody is going to advance.
+ */
+const SHARED: $ReadOnlyArray<Shared> = [
+  {
+    what: "the tests, hooks and spies this package registered",
+    restore: reset,
+  },
+  {
+    // `process.env` belongs to the process. `uft.stubEnv("NODE_ENV",
+    // "production")` in one file is still set when the next one imports, and
+    // the file that fails is the one that read it.
+    what: "environment variables `uft.stubEnv` replaced",
+    restore: unstubAllEnvs,
+  },
+  {
+    // `globalThis` likewise, and worse: a stubbed `fetch` makes the next file
+    // talk to a stand-in that does not know about it.
+    what: "globals `uft.stubGlobal` replaced",
+    restore: unstubAllGlobals,
+  },
+  {
+    // Worse than a leaked value, and worse in a way that hides it. A leaked
+    // stub makes the next file read something wrong, which arrives as an
+    // assertion naming the value. A leaked clock makes the next file's
+    // `setTimeout` never fire — including the one `withTimeout` races each
+    // case against — so the file hangs with nothing on screen until `uf`'s own
+    // deadline kills the worker, and the report names the file that waited
+    // rather than the file that stopped time.
+    what: "the clock, whatever `uft.useFakeTimers` did to it",
+    restore: restoreRealClock,
+  },
+  {
+    // 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".
+    what: "modules `uft.mock` stood in for",
+    restore: resetModuleState,
+  },
+  {
+    what: "the document, if this process has one",
+    restore: restoreDocument,
+  },
+];
+
+/**
+ * Hand the next file a document nobody else has written to.
+ *
+ * The document is process-wide in a way that is easy to miss, because nothing
+ * in this package installs it: `@uniflowed/react-testing` puts one on the
+ * global object the first time a test renders and deliberately keeps it for
+ * the life of the process — replacing it would strand every React root already
+ * mounted in the old one. So one document serves every file a worker runs, and
+ * what a file leaves in it is what the next file queries.
+ *
+ * Its *contents* are put back rather than the document itself, and "back"
+ * means empty: a file is handed the body it would have had if it had installed
+ * the document itself. `cleanup()` already unmounts what `render` mounted, and
+ * that is not the leak — the leak is markup a test wrote into the body by
+ * hand, which a hydration test must do because hydration is React attaching to
+ * markup that is already there. `rsc-split.test.js` and `streaming.test.js`
+ * both `replaceChildren` into the body, and the file after them in that worker
+ * started with somebody else's page.
+ *
+ * Read through `globalThis` and guarded by `typeof`, because a worker running
+ * a suite that never renders has no `document` at all and must not pay for
+ * one — and because on a host that *is* a browser this is the page, whose body
+ * a run of `uf test` has no business emptying. It only ever clears a body that
+ * a test process is using as scratch space, which is every case this can
+ * reach: the shim's document, or a page the project chose to run its own tests
+ * in.
+ */
+function restoreDocument(): void {
+  if (typeof globalThis.document === "undefined") {
+    return;
+  }
+  const body = globalThis.document.body;
+  if (body == null) {
+    // A document a parser produced need not have one, and a document with no
+    // body is a document with nothing to put back.
+    return;
+  }
+  body.replaceChildren();
+  // The attributes too, and not for tidiness: `<body class="dark">` is how a
+  // theme test says what it is testing, and a file that leaves one behind
+  // makes the next file's "the page is in light mode" false for a reason it
+  // cannot see. Read into an array first — removing an attribute while
+  // iterating a live list is the loop that skips every other entry.
+  for (const name of [...body.getAttributeNames()]) {
+    body.removeAttribute(name);
+  }
+}
+
+/**
+ * Put back everything the file that just ran may have changed.
+ *
+ * Called by `../worker.js` before it imports the next file. Nothing here
+ * reports a file for having changed any of this: a file is *allowed* to — that
+ * is what the `uft` namespace is for — and the contract is that the change
+ * does not outlive the file, not that it never happened.
+ *
+ * Every entry is attempted even after one has thrown, and the first failure is
+ * raised afterwards under the name of what it could not put back. Stopping at
+ * the first would leave the four entries behind it un-restored, which is the
+ * defect this module exists to prevent arriving by a new route — and a bare
+ * throw from one of these used to say only that something in the runner failed
+ * between two files.
+ */
+export function restoreSharedState(): void {
+  let failure: { readonly what: string, readonly thrown: mixed } | null = null;
+  for (const shared of SHARED) {
+    try {
+      shared.restore();
+    } catch (thrown) {
+      failure ??= { what: shared.what, thrown };
+    }
+  }
+  if (failure != null) {
+    const cause = failure.thrown;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`@uniflowed/test could not put back ${failure.what}: ${message}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.0.0-alpha.13",
+  "version": "0.0.0-alpha.15",
   "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.13"
+    "@uniflowed/host": "0.0.0-alpha.15"
   }
 }

package/worker.js

@@ -53,10 +53,8 @@ import { writeChangedSnapshots } from "./internal/snapshot.js";
 import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { reset } from "./internal/registry.js";
-import { resetModuleState } from "./internal/modules.js";
+import { restoreSharedState } from "./internal/isolation.js";
 import { run } from "./internal/run.js";
-import { unstubAllEnvs, unstubAllGlobals } from "./internal/namespace.js";
 
 /** What `uf` sends for one file. */
 type Request = {|
@@ -140,22 +138,21 @@ function write(event: { readonly [string]: mixed }): void {
  */
 async function runFile(request: Request, generation: number): Promise<void> {
   const started = performance.now();
-  reset();
-  // Every environment variable and global the previous file replaced goes back
-  // too. A spy lives in the registry `reset` clears, but a stub is a write to
-  // something the whole process shares: `uft.stubEnv("NODE_ENV", "production")`
-  // stays set for every later file this worker serves, and `uf test` fans files
-  // across workers by size, so which files those are changes with the timings
-  // file. That is a suite whose result depends on its schedule — and worse, one
-  // whose failure names the file that read the value rather than the file that
-  // wrote it. See ubugeeei-prod/uf#417.
-  unstubAllEnvs();
-  unstubAllGlobals();
-  // 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();
+  // Everything the previous file changed and this package shares with it goes
+  // back: the registry, the stubbed environment and globals, the clock, the
+  // module stand-ins, and the document. What each of those is and why it is on
+  // the list is `internal/isolation.js`, which is one place rather than five
+  // calls here — a worker serves many files out of one process, `uf test` fans
+  // files across workers by size, and a leak therefore makes the *result* of a
+  // suite a function of the timings file rather than of the code under test.
+  // See ubugeeei-prod/uf#417, #581 and #607, which are that sentence three
+  // times over.
+  //
+  // Before the import rather than after the run, so a file that throws while
+  // loading still hands the next one a clean process.
+  restoreSharedState();
+  // Not a restore, and so not on that list: this is the output budget for the
+  // file about to run, rather than something the previous file left behind.
   output.startFile();
 
   try {