@uniflowed/test 0.0.0-alpha.4 → 0.0.0-alpha.5

package/internal/expect.js

@@ -88,6 +88,24 @@ 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
+ *
+ * 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.
+ *
+ * `mixed` with a cast at the call would move the same unsoundness one line
+ * without checking anything, because the caller is `bind`, whose result is
+ * `$FlowFixMe` and whose result's result is `expect`, also `$FlowFixMe`. The
+ * type that makes any of this checked is a written-out matcher interface —
+ * one signature per matcher, plus `.not`, `.resolves` and `.rejects` — which
+ * is what `expect`'s own annotation is waiting for. Until that exists, a
+ * narrower type here would be precision nobody can reach.
  */
 function verdicts(received: mixed): {
   readonly [string]: (...args: $ReadOnlyArray<any>) => Verdict,

package/internal/output.js

@@ -21,25 +21,58 @@
 // # Why this is its own module
 //
 // Two callers need it and neither owns it: `worker.js` installs the capture at
-// start-up, and `run.js` says which case is running so a chunk can be named.
-// "Who printed this" is also state with a lifetime of its own — set around a
-// case's body and hooks, cleared between them — exactly like the snapshot key
-// in `snapshot.js`, and for the same reason it lives beside the thing it
-// describes rather than inside either caller.
+// start-up, and `run.js` runs each case inside the ownership kept here, so a
+// chunk can be named. "Who printed this" is also state with a lifetime of its
+// own — one case's hooks and body — exactly like the snapshot key in
+// `snapshot.js`, and for the same reason it lives beside the thing it describes
+// rather than inside either caller.
 //
 // # What "the test that printed it" means
 //
-// The name a chunk carries is the case the *worker* is running when the chunk
-// arrives, which is not the same as the case whose code produced it. A
-// `setTimeout` a test leaves behind prints while the next case is running and
-// is filed under that one; a chunk from no case at all is filed under the
-// file.
+// The case whose *asynchronous context* the write happened in, which is the
+// case whose code produced it.
 //
-// Getting this exactly right needs the printing to be tied to the asynchronous
-// context the case ran in — `AsyncLocalStorage` and everything under it — and
-// that is a bigger change than this module, because it has to reach the
-// scheduler that runs the cases. It is written down here rather than left to
-// be discovered from a confusing report. See ubugeeei-prod/uf#207.
+// The obvious answer was a module-level variable the runner set before a case
+// and cleared after it, and it was wrong in one shape that matters: the name a
+// chunk carried was whatever the worker happened to be running when the chunk
+// arrived. A `setTimeout` a test left behind fires while the *next* case is
+// running, so the line it printed was reported under that next case — a test
+// accused of printing something it never printed, which is worse than not
+// naming it at all, because a reader chasing the message finds it under code
+// that does not contain it. See ubugeeei-prod/uf#207.
+//
+// So the owner is an `AsyncLocalStorage`, and what `run.js` calls is
+// `runInTest` rather than an `enterTest` / `exitTest` pair: the store is only
+// carried by work started *inside* the case, so the case's setup, body and
+// teardown have to run within it. Everything they schedule inherits it,
+// whenever it eventually runs.
+//
+// # When there is no owner
+//
+// `getStore()` answers nothing outside a case, and a chunk with no owner is
+// filed under the file — which is right for an import, a `beforeAll`, or a
+// straggler from a case that is long gone.
+//
+// It is also the answer on a host whose storage does not reach the callback.
+// Deno 1.31 has `AsyncLocalStorage` and propagates it across `await`, but not
+// through `setTimeout`, so a detached callback there is filed under the file
+// rather than under the case that scheduled it. That degradation is the point:
+// of the two ways to be less than exact, naming the file says less, and naming
+// the next case says something false.
+//
+// `node:async_hooks` itself is not guarded for, because a guard could not run.
+// Node, Deno and Bun all provide it under the `node:` specifier, and a host
+// that had no `node:` builtins could not start this worker at all — `node:util`
+// is imported below, `node:readline` and `node:url` by `worker.js`. A `typeof`
+// check around the constructor would only ever execute on a host where this
+// module had already linked.
+//
+// The one thing this does not answer is a straggler that outlives its *file*:
+// the worker runs the next file in the same process, and a chunk still carrying
+// a name from the file before is a name the next file's report has no test for.
+// The host files it under the file it arrived in, which is honest but not
+// exact, and closing it properly needs the file's generation in the protocol.
+// That is ubugeeei-prod/uf#203, and it is not this module's to fix.
 
 // # Bounds
 //
@@ -49,6 +82,7 @@
 // nothing after it is kept. The budget starts over for each file, so a chatty
 // file does not silence the next one in the same worker.
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { format, inspect } from "node:util";
 
 import { userFrames } from "./frames.js";
@@ -95,9 +129,16 @@ const DECODER = new TextDecoder();
 /** What a stream's `write` calls when it has taken the chunk. */
 type WriteCallback = () => mixed;
 
+/**
+ * The case a write belongs to, kept in the asynchronous context it ran in.
+ *
+ * Full names rather than a record, because that is the whole of what a chunk
+ * needs to say and the protocol carries it as a string either way.
+ */
+const owner: AsyncLocalStorage<string> = new AsyncLocalStorage();
+
 let sink: OutputSink | null = null;
 let raw: ((chunk: string) => void) | null = null;
-let current: string | null = null;
 let captured = 0;
 let stopped = false;
 
@@ -159,7 +200,7 @@ function capture(stream: OutputStream, text: string): void {
     stopped = true;
   }
   captured += kept.length;
-  to({ stream, test: current, text: kept });
+  to({ stream, test: owner.getStore() ?? null, text: kept });
 }
 
 /** A stand-in for `process.stdout.write` / `process.stderr.write`. */
@@ -236,25 +277,33 @@ export function install(to: OutputSink): (chunk: string) => void {
 }
 
 /**
- * Say which case is running, so what it prints can be named.
+ * Run `body` as `name`, so what it prints — and what it leaves behind to print
+ * later — is filed under that case.
  *
- * The runner calls this around a case's body and hooks and clears it between
- * them: output written while the module is being imported, from a `beforeAll`,
- * or after the last case finished belongs to the file, not to whichever case
- * happened to run last.
+ * The runner wraps one case's `beforeEach`, body and `afterEach` in a single
+ * call, because those are the one case's work. Whatever `body` returns is
+ * returned unchanged, so an `await` on this is an `await` on the case.
+ *
+ * Nothing here needs an "and now nothing is running" counterpart. Output from
+ * an import, a `beforeAll` or a case that has already been reported was never
+ * inside this call, so it has no owner and is the file's — which is the
+ * property the previous module-level variable had to be reset to keep, and
+ * kept only for as long as nothing straggled.
  */
-export function enterTest(name: string): void {
-  current = name;
-}
-
-/** Say that no case is running. */
-export function exitTest(): void {
-  current = null;
+export function runInTest<T>(name: string, body: () => T): T {
+  return owner.run(name, body);
 }
 
-/** Start one file's output budget over, with no case running. */
+/**
+ * Start one file's output budget over.
+ *
+ * Only the budget: there is no current case to clear, because a case's
+ * ownership lives in the callbacks it started rather than in this module. A
+ * straggler from the file before still carries the name it was written under,
+ * which the host cannot match to a test of the new file and files under that
+ * file instead. See ubugeeei-prod/uf#203.
+ */
 export function startFile(): void {
   captured = 0;
   stopped = false;
-  current = null;
 }

package/internal/run.js

@@ -193,34 +193,40 @@ async function runCase(
 
   const timeoutMs = test.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   let outcome: Outcome = { status: "passed" };
-  // From here to the end of teardown is exactly the window in which this
-  // case's own code runs, so it is exactly the window whose printing is this
-  // case's. The cases above never reach it: nothing runs for a `todo`, a
-  // `skip` or a filtered-out case, so nothing of theirs can print.
-  output.enterTest(name);
-  try {
-    for (const hook of context.beforeEach) {
-      await withTimeout(hook, timeoutMs);
-    }
-    await withTimeout(test.body, timeoutMs);
-  } catch (thrown) {
-    outcome = failure(thrown);
-  }
-  // Teardown runs whatever happened above, and only reports its own failure
-  // when the body had not already failed.
-  for (const hook of context.afterEach) {
+  // Setup, body and teardown run *inside* the case's output context, and that
+  // nesting is the whole of the fix for #207. What names a printed line is no
+  // longer where the runner had got to when the line arrived — which named the
+  // next case for anything a `setTimeout` left behind — but which case's work
+  // the write descends from. A callback scheduled here keeps this name however
+  // late it fires.
+  //
+  // The cases above never reach this: nothing runs for a `todo`, a `skip` or a
+  // filtered-out case, so nothing of theirs can print.
+  await output.runInTest(name, async () => {
     try {
-      await withTimeout(hook, timeoutMs);
+      for (const hook of context.beforeEach) {
+        await withTimeout(hook, timeoutMs);
+      }
+      await withTimeout(test.body, timeoutMs);
     } catch (thrown) {
-      if (outcome.status === "passed") {
-        outcome = failure(thrown);
+      outcome = failure(thrown);
+    }
+    // Teardown runs whatever happened above, and only reports its own failure
+    // when the body had not already failed.
+    for (const hook of context.afterEach) {
+      try {
+        await withTimeout(hook, timeoutMs);
+      } catch (thrown) {
+        if (outcome.status === "passed") {
+          outcome = failure(thrown);
+        }
       }
     }
-  }
-  // No test is running once this one is reported, so a snapshot taken outside
-  // one fails with something better than a key belonging to whichever test
-  // happened to run last, and a line printed outside one is the file's.
-  output.exitTest();
+  });
+  // The `await` above resumes outside the context it entered, so this line and
+  // everything after it belong to no case again — a line printed between cases
+  // is the file's, and a snapshot taken outside one fails with something better
+  // than a key belonging to whichever test happened to run last.
   snapshot.exitTest();
   report(outcome);
   return outcome.status !== "failed";
@@ -238,6 +244,7 @@ async function runSuite(
   onlyMode: boolean,
   emit: (result: Result) => void,
   state: {| bail: boolean |},
+  setUpAncestors: () => Promise<void>,
 ): Promise<boolean> {
   const skipped = context.skipped || node.modifier === "skip" || node.modifier === "todo";
   const onlyPath = !onlyMode || context.onlyPath || node.modifier === "only";
@@ -252,11 +259,18 @@ async function runSuite(
 
   // `beforeAll` is deferred until a case in this suite actually runs, so a
   // fully skipped suite never sets anything up. `afterAll` mirrors it.
+  //
+  // "In this suite" means anywhere under it. A suite whose children are all
+  // suites has no case of its own, and setting up only for a direct child left
+  // 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.
   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);
@@ -299,7 +313,7 @@ async function runSuite(
       const ok = await runCase(child, childContext, options, emit);
       passed = passed && ok;
     } else {
-      const ok = await runSuite(child, inner, options, onlyMode, emit, state);
+      const ok = await runSuite(child, inner, options, onlyMode, emit, state, setUpOnce);
       passed = passed && ok;
     }
   }
@@ -333,5 +347,5 @@ export async function run(options: RunOptions, emit: (result: Result) => void):
     skipped: false,
     onlyPath: !onlyMode,
   };
-  await runSuite(root, context, options, onlyMode, emit, { bail: false });
+  await runSuite(root, context, options, onlyMode, emit, { bail: false }, async () => {});
 }

package/package.json

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

package/worker.js

@@ -7,24 +7,48 @@
 // Flow loader, so the module is transformed by the same `uf transform` the
 // build uses), runs what it registered, and writes one event per line back.
 //
-//   → {"file": "src/math.test.js", "filter": "adds", "timeoutMs": 5000}
-//   ← {"event": "test", "name": "math > adds", "status": "passed", …}
-//   ← {"event": "output", "stream": "stdout", "test": "math > adds", "text": "hi\n"}
-//   ← {"event": "file", "status": "completed", "durationMicros": 1234}
+//   → {"file": "src/math.test.js", "filter": "adds", "timeoutMs": 5000, "generation": 7}
+//   ← {"event": "test", "name": "math > adds", "status": "passed", "generation": 7, …}
+//   ← {"event": "output", "stream": "stdout", "test": "math > adds", "text": "hi\n", "generation": 7}
+//   ← {"event": "file", "status": "completed", "durationMicros": 1234, "generation": 7}
 //
-// Three decisions worth stating. Results are streamed as they happen rather
+// Four decisions worth stating. Results are streamed as they happen rather
 // than batched at the end, so `uf test` can draw progress and `--bail` can stop
 // a long run early. A file that throws while being *imported* is a file result,
 // not a test result: there were no tests to fail, and saying "0 tests" for a
-// module that could not load would be a lie. And the protocol does not share
-// its stream with the tests: a test's own printing becomes an `output` event
+// module that could not load would be a lie. The protocol does not share its
+// stream with the tests: a test's own printing becomes an `output` event
 // (`internal/output.js`), so a `console.log` cannot land in the middle of a
-// line `uf` is parsing.
+// line `uf` is parsing. And every event says which request it belongs to —
+// see "Which file an event belongs to" below.
 //
 // This module runs on import by design — it is a process entry point, the way
 // `@uniflowed/vite`'s loaders are.
+//
+// # Which file an event belongs to
+//
+// One worker's events are one stream, and a file's code outlives the file: a
+// `setTimeout` nobody awaited fires while the *next* file is running, and what
+// it prints used to be reported under a test in a different file. The same held
+// for anything else the abandoned work reached — including the unhandled
+// rejection handler at the bottom of this module, which ends a file.
+//
+// So an event says which request it came from rather than leaving `uf` to
+// assume it came from the one in progress. `uf` numbers the requests it sends;
+// this module runs each file inside an `AsyncLocalStorage` holding that number,
+// and stamps every event with what the storage says *at the moment of writing*.
+// Work a file leaves behind inherits its store however late it runs, so a
+// straggler carries the generation of the file that scheduled it, and `uf`
+// drops it instead of handing it to whatever is running now. See
+// ubugeeei-prod/uf#203 and `crates/uf_test/src/host.rs`.
+//
+// A module-level "the file we are serving now" variable was the obvious answer
+// and it is exactly the bug: at the moment the straggler writes, the file being
+// served *is* the next one. The number has to come from where the work was
+// started, which is what asynchronous storage is.
 
 import * as output from "./internal/output.js";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { writeChangedSnapshots } from "./internal/snapshot.js";
 import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -37,8 +61,30 @@ type Request = {|
   readonly file: string,
   readonly filter?: string | null,
   readonly timeoutMs?: number,
+  /**
+   * Which request this is, counting from one within this worker.
+   *
+   * Optional only for a `uf` older than the field; `serve` falls back to its
+   * own count of the requests it has served, which is the same number.
+   */
+  readonly generation?: number,
 |};
 
+/**
+ * The request whose work the code running right now descends from.
+ *
+ * Read by `write`, so a callback a finished file left behind stamps its events
+ * with that file's number rather than with the number of the file the worker
+ * has moved on to.
+ *
+ * `node:async_hooks` is not guarded for: Node, Deno and Bun all provide it
+ * under the `node:` specifier, and a host with no `node:` builtins could not
+ * link this module at all — `node:readline` and `node:url` are imported above.
+ * A host whose storage does not reach a particular callback is a different
+ * matter and is handled by the fallback in `write`.
+ */
+const serving: AsyncLocalStorage<number> = new AsyncLocalStorage();
+
 /**
  * The protocol's own stdout, and the capture that gave it up.
  *
@@ -60,16 +106,35 @@ const emit: (chunk: string) => void = output.install((chunk) => {
   });
 });
 
+/**
+ * Write one event, stamped with the request it belongs to.
+ *
+ * Stamped here rather than at each of the five places that build an event, so
+ * there is no way to write one without a generation — the module-level
+ * unhandled rejection handler included, which is the one that most needed it.
+ *
+ * `0` is what an event carries when the storage has nothing to say: a write
+ * from outside any request (a malformed request line, which `uf` answers to
+ * immediately), or a host that does not carry a store into the callback that
+ * wrote it — Deno 1.31 does not carry one through `setTimeout`, and Bun does
+ * not carry one into `unhandledRejection`. `uf` reads `0` as "the file being
+ * served", which is what every event meant before this field existed: of the
+ * two ways to be less than exact, saying nothing about a straggler is the
+ * behaviour that was already there, and refusing an unstamped `file` event
+ * would hang a file that had in fact answered.
+ */
 function write(event: { readonly [string]: mixed }): void {
-  emit(`${JSON.stringify(event)}\n`);
+  emit(`${JSON.stringify({ ...event, generation: serving.getStore() ?? 0 })}\n`);
 }
 
 /**
  * Import and run one file.
  *
- * The module is imported with a cache-busting query so a watch-mode rerun in
- * the same worker sees the edited file rather than the one the module registry
- * already holds.
+ * `generation` is the request's number, and it does two jobs with one value:
+ * it busts the module cache so a watch-mode rerun in the same worker sees the
+ * edited file rather than the one the registry already holds, and — through
+ * the `serving` store this runs inside — it is what every event written from
+ * this file, or from anything this file leaves behind, is stamped with.
  */
 async function runFile(request: Request, generation: number): Promise<void> {
   const started = performance.now();
@@ -133,10 +198,15 @@ async function runFile(request: Request, generation: number): Promise<void> {
  * a time, because two files sharing a process would share globals and module
  * state, and a test suite that passes alone but fails beside another is the
  * worst failure a runner can produce.
+ *
+ * "In order" bounds what the worker *starts*, not what a file leaves running,
+ * which is why each file runs inside `serving`. The store is entered here and
+ * not in `runFile` so that the whole of a file's work, its module import
+ * included, is inside it.
  */
 function serve(): void {
   let queue: Promise<void> = Promise.resolve();
-  let generation = 0;
+  let served = 0;
 
   createInterface({ input: process.stdin }).on("line", (line) => {
     if (line.trim() === "") {
@@ -146,6 +216,9 @@ function serve(): void {
     try {
       request = JSON.parse(line);
     } catch (error) {
+      // Outside any `serving.run`, so this is stamped `0` — which is right:
+      // there is no request to attribute it to, and `uf` is waiting for an
+      // answer to the line it just wrote.
       write({
         event: "file",
         status: "run-failed",
@@ -153,9 +226,14 @@ function serve(): void {
       });
       return;
     }
-    generation += 1;
-    const at = generation;
-    queue = queue.then(() => runFile(request, at));
+    served += 1;
+    // `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)));
   });
 
   process.stdin.on("close", () => {
@@ -165,6 +243,13 @@ function serve(): void {
 
 // Unhandled rejections would otherwise take the worker down mid-file with no
 // explanation; reporting one as a file failure keeps the run honest.
+//
+// The file it fails is whichever one the rejected promise was created in, not
+// whichever one is running when Node gets round to reporting it: `write` reads
+// the store, and on Node the store follows the promise. That matters because
+// this is a `file` event and a `file` event *ends* a file — a promise the
+// previous file abandoned used to end the next one, with a message from code
+// that file does not contain.
 process.on("unhandledRejection", (reason: mixed) => {
   const error = reason instanceof Error ? reason : new Error(String(reason));
   write({