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

package/internal/namespace.js

@@ -0,0 +1,251 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: the `uft` namespace.
+//
+// The operations Vitest groups under `vi`, under uf's own name. The *shape* is
+// what a migration needs — `fn`, `spyOn`, `stubEnv`, `useFakeTimers` doing what
+// they do elsewhere — and borrowing another tool's brand for it would be
+// claiming something uf has not earned.
+//
+// A namespace rather than loose named exports, because several of these names
+// are generic enough to collide in a test file: `@uniflowed/testing` re-exports
+// both this package and `@uniflowed/react-testing`, and both have a `waitFor`.
+//
+// `uft` rather than `uf`, and rather than `uf.test`. A bare `uf` is the command
+// and the project, and a test file would be using the name for something much
+// smaller than everything else in the toolchain answers to. `uf.test` reads as
+// the `test` function this package also exports, which is `it` under another
+// name — two very different things one dot apart. `uft` is three characters,
+// belongs to nothing else, and is what a reader types a hundred times a file.
+//
+// What is *not* here is as deliberate. `uft.mock` intercepts a module before it
+// is imported, which needs the loader rather than the runner, and uf's loader is
+// `@uniflowed/host` — so it is a real piece of work rather than a wrapper, and
+// it is not pretended at here. A missing binding throws with what it would take;
+// a binding that silently did nothing would be worse than not having it.
+
+import { clearAllMocks, fn, resetAllMocks, restoreAllMocks, spyOn } from "./spy.js";
+import * as timers from "./timers.js";
+
+/** Environment variables `stubEnv` replaced, and what they were. */
+const stubbedEnv: Map<string, string | void> = new Map();
+
+/** Globals `stubGlobal` replaced, and what they were. */
+const stubbedGlobals: Map<string, { readonly owned: boolean, readonly value: mixed }> = new Map();
+
+/**
+ * Raised for a `uft` namespace binding that is not implemented.
+ *
+ * Names what the binding needs rather than only that it is missing: `uft.mock`
+ * is absent because module interception belongs to the loader, and a reader who
+ * knows that can decide whether to wait or to restructure the test.
+ */
+export class UnsupportedError extends Error {
+  /** The binding that was called. */
+  binding: string;
+
+  constructor(binding: string, reason: string) {
+    super(`uft.${binding} is not implemented yet: ${reason}`);
+    this.name = "UnsupportedError";
+    this.binding = binding;
+  }
+}
+
+/**
+ * Read the process environment, whichever host this is.
+ *
+ * Node, Deno and Bun all expose `process.env`; Deno also has `Deno.env`, and
+ * reaching for `process` first keeps one code path across the three.
+ */
+function environment(): { [string]: string } | null {
+  const host = globalThis as $FlowFixMe;
+  return host.process?.env ?? null;
+}
+
+/**
+ * Replace an environment variable for the rest of the test.
+ *
+ * Undone by `unstubAllEnvs`, which the runner calls between files — a stub that
+ * outlived its test would be a test that passes alone and fails in a suite.
+ */
+export function stubEnv(name: string, value: string | void): void {
+  const env = environment();
+  if (env == null) {
+    throw new UnsupportedError("stubEnv", "this host exposes no process environment");
+  }
+  if (!stubbedEnv.has(name)) {
+    stubbedEnv.set(name, Object.hasOwn(env, name) ? env[name] : undefined);
+  }
+  if (value === undefined) {
+    delete env[name];
+  } else {
+    env[name] = value;
+  }
+}
+
+/** Put every environment variable `stubEnv` replaced back. */
+export function unstubAllEnvs(): void {
+  const env = environment();
+  if (env == null) {
+    stubbedEnv.clear();
+    return;
+  }
+  for (const [name, previous] of stubbedEnv) {
+    if (previous === undefined) {
+      delete env[name];
+    } else {
+      env[name] = previous;
+    }
+  }
+  stubbedEnv.clear();
+}
+
+/**
+ * Replace a global for the rest of the test.
+ *
+ * Whether the global was the object's own property is recorded, because putting
+ * back an inherited one by assignment would leave a copy that shadows whatever
+ * it was inherited from.
+ */
+export function stubGlobal(name: string, value: mixed): void {
+  const host = globalThis as $FlowFixMe;
+  if (!stubbedGlobals.has(name)) {
+    stubbedGlobals.set(name, {
+      owned: Object.hasOwn(host, name),
+      value: host[name],
+    });
+  }
+  host[name] = value;
+}
+
+/** Put every global `stubGlobal` replaced back. */
+export function unstubAllGlobals(): void {
+  const host = globalThis as $FlowFixMe;
+  for (const [name, previous] of stubbedGlobals) {
+    if (previous.owned) {
+      host[name] = previous.value;
+    } else {
+      delete host[name];
+    }
+  }
+  stubbedGlobals.clear();
+}
+
+/** How often `waitFor` re-runs its body while it is failing. */
+const WAIT_INTERVAL_MS = 20;
+
+/** How long `waitFor` keeps trying before giving up. */
+const WAIT_TIMEOUT_MS = 1_000;
+
+/**
+ * Run `body` until it stops throwing, or the timeout passes.
+ *
+ * The last failure is what is raised, not a timeout — "expected 2, got 1" says
+ * what went wrong, and "timed out" says only that something did.
+ */
+export async function waitFor<T>(
+  body: () => T | Promise<T>,
+  options?: { readonly timeout?: number, readonly interval?: number },
+): Promise<T> {
+  const timeout = options?.timeout ?? WAIT_TIMEOUT_MS;
+  const interval = options?.interval ?? WAIT_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  let last: mixed = null;
+
+  for (;;) {
+    try {
+      return await body();
+    } catch (thrown) {
+      last = thrown;
+    }
+    if (Date.now() >= deadline) {
+      throw last ?? new Error(`uft.waitFor: gave up after ${timeout}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+
+/** Run `body` until it returns something truthy, or the timeout passes. */
+export async function waitUntil(
+  body: () => mixed | Promise<mixed>,
+  options?: { readonly timeout?: number, readonly interval?: number },
+): Promise<mixed> {
+  return waitFor(async () => {
+    const value = await body();
+    if (value == null || value === false) {
+      throw new Error("uft.waitUntil: the condition is not true yet");
+    }
+    return value;
+  }, options);
+}
+
+/**
+ * Hand a value back with its mock methods visible to the type checker.
+ *
+ * Purely a type-level convenience, exactly as in Vitest: at runtime it is the
+ * identity function, and its whole job is letting a test write
+ * `uft.mocked(client.send).mockReturnValue(…)` without a cast.
+ */
+export function mocked<T>(value: T): $FlowFixMe {
+  return value;
+}
+
+/** Not implemented, and specific about what it would take. */
+function unsupported(binding: string, reason: string): () => empty {
+  return () => {
+    throw new UnsupportedError(binding, reason);
+  };
+}
+
+/** The reason every module-interception binding is absent. */
+const NEEDS_LOADER =
+  "intercepting a module before it is imported belongs to the loader " +
+  "(`@uniflowed/host`), not to the runner, and uf has not wired it yet";
+
+/**
+ * The `uft` namespace.
+ *
+ * A frozen object rather than a class: it is a namespace, nothing about it is
+ * per-instance, and freezing it means a test cannot leave a monkey-patch behind
+ * for the next one.
+ */
+export const uft: $FlowFixMe = Object.freeze({
+  fn,
+  spyOn,
+  mocked,
+
+  clearAllMocks,
+  resetAllMocks,
+  restoreAllMocks,
+
+  stubEnv,
+  unstubAllEnvs,
+  stubGlobal,
+  unstubAllGlobals,
+
+  waitFor,
+  waitUntil,
+
+  // The clock a test controls. A test about "after five minutes the session
+  // expires" should not take five minutes.
+  useFakeTimers: timers.useFakeTimers,
+  useRealTimers: timers.useRealTimers,
+  isFakeTimers: timers.isFaked,
+  advanceTimersByTime: timers.advanceTimersByTime,
+  advanceTimersByTimeAsync: timers.advanceTimersByTimeAsync,
+  advanceTimersToNextTimer: timers.advanceTimersToNextTimer,
+  runAllTimers: timers.runAllTimers,
+  runOnlyPendingTimers: timers.runOnlyPendingTimers,
+  getTimerCount: timers.getTimerCount,
+  setSystemTime: timers.setSystemTime,
+  getMockedSystemTime: timers.getMockedSystemTime,
+
+  // Module interception. Absent rather than faked; see `NEEDS_LOADER`.
+  mock: unsupported("mock", NEEDS_LOADER),
+  doMock: unsupported("doMock", NEEDS_LOADER),
+  unmock: unsupported("unmock", NEEDS_LOADER),
+  doUnmock: unsupported("doUnmock", NEEDS_LOADER),
+  importActual: unsupported("importActual", NEEDS_LOADER),
+  importMock: unsupported("importMock", NEEDS_LOADER),
+  resetModules: unsupported("resetModules", NEEDS_LOADER),
+});

package/internal/output.js

@@ -0,0 +1,260 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: what a test printed, attributed to the test
+// that printed it.
+//
+// The worker and the tests it runs share one stdout, and the worker's protocol
+// is one JSON object per line on it. A `console.log` in a test therefore wrote
+// a line into the middle of that protocol, `uf` read it as an event it could
+// not parse, and the whole file died — a green suite killed by a debugging
+// statement somebody left in.
+//
+// So the stream stops being shared. This module takes over `console` and the
+// two `write` methods a test can reach directly, turns everything written
+// through them into an ordinary protocol event, and hands the caller the real
+// `process.stdout.write` it took — the protocol keeps the raw stream, and it
+// is the only thing that has it. A test that prints something shaped exactly
+// like a protocol line is then a string inside a JSON field, which is the
+// point: the escaping is what makes the channel robust, not a filter that
+// tries to recognise the imposter.
+//
+// # 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.
+//
+// # 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.
+//
+// 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.
+
+// # Bounds
+//
+// A test that prints in a loop must not be able to fill the pipe, the worker's
+// memory or the report, so one file's captured output is bounded and the
+// bound is announced rather than hidden: the chunk that reaches it says so and
+// 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 { format, inspect } from "node:util";
+
+import { userFrames } from "./frames.js";
+
+/** Which of the process's two streams a chunk was written to. */
+export type OutputStream = "stdout" | "stderr";
+
+/** One thing a test — or the file around it — printed. */
+export type OutputChunk = {|
+  readonly stream: OutputStream,
+  /** Full name of the case that was running, or `null` when none was. */
+  readonly test: string | null,
+  /** The text as it would have reached the terminal, newline included. */
+  readonly text: string,
+|};
+
+/** Where captured output goes. */
+export type OutputSink = (chunk: OutputChunk) => void;
+
+/**
+ * Longest single write kept, in UTF-16 code units.
+ *
+ * A test that prints a megabyte-long serialised fixture meant to print
+ * something; the first few kilobytes of it are what says what happened, and
+ * the rest is not a report's to carry.
+ */
+export const MAX_CHUNK_LENGTH: number = 8 * 1024;
+
+/** Most output kept from one file, in UTF-16 code units. */
+export const MAX_FILE_LENGTH: number = 128 * 1024;
+
+/** Which stream each replaced `console` method writes to, as Node routes them. */
+const CONSOLE_STREAMS: { readonly [string]: OutputStream } = {
+  log: "stdout",
+  info: "stdout",
+  debug: "stdout",
+  warn: "stderr",
+  error: "stderr",
+};
+
+/** Decoder for a `write` that was handed bytes rather than a string. */
+const DECODER = new TextDecoder();
+
+/** What a stream's `write` calls when it has taken the chunk. */
+type WriteCallback = () => mixed;
+
+let sink: OutputSink | null = null;
+let raw: ((chunk: string) => void) | null = null;
+let current: string | null = null;
+let captured = 0;
+let stopped = false;
+
+/**
+ * The globals to patch, in one place.
+ *
+ * The one untyped expression in this module, and it is the trust boundary
+ * itself: `console` and `process.stdout` are the host's, their libdef types
+ * are read-only, and replacing them is exactly what this module is for.
+ */
+function host(): $FlowFixMe {
+  return globalThis;
+}
+
+/**
+ * `args` rendered the way `console.log` renders them.
+ *
+ * Node's console hands its arguments to `util.format`, and this is that in two
+ * cases rather than one, because `format`'s first parameter is the template:
+ * with a leading string it substitutes `%s`, `%d`, `%o` and the rest and
+ * inspects whatever is left over, and with anything else there is no template
+ * to substitute into, so every argument is inspected and the results joined
+ * with a space. Both are what Node prints.
+ */
+function formatArguments(args: $ReadOnlyArray<mixed>): string {
+  const [first, ...rest] = args;
+  if (typeof first === "string") {
+    return format(first, ...rest);
+  }
+  return args.map((value) => (typeof value === "string" ? value : inspect(value))).join(" ");
+}
+
+/** The text of one `write` argument, whether it arrived as bytes or a string. */
+function textOf(chunk: mixed): string {
+  if (typeof chunk === "string") {
+    return chunk;
+  }
+  if (chunk instanceof Uint8Array) {
+    return DECODER.decode(chunk);
+  }
+  return String(chunk);
+}
+
+/**
+ * Record one piece of output, within the file's budget.
+ *
+ * Silently doing nothing when no sink is installed is deliberate: a test that
+ * prints must never fail because of how it was run.
+ */
+function capture(stream: OutputStream, text: string): void {
+  const to = sink;
+  if (to == null || stopped || text === "") {
+    return;
+  }
+  let kept = text.length > MAX_CHUNK_LENGTH ? `${text.slice(0, MAX_CHUNK_LENGTH)}…\n` : text;
+  const room = MAX_FILE_LENGTH - captured;
+  if (kept.length >= room) {
+    kept = `${kept.slice(0, Math.max(room, 0))}\n[uf] output stopped after ${MAX_FILE_LENGTH} characters\n`;
+    stopped = true;
+  }
+  captured += kept.length;
+  to({ stream, test: current, text: kept });
+}
+
+/** A stand-in for `process.stdout.write` / `process.stderr.write`. */
+function writer(
+  stream: OutputStream,
+): (chunk: mixed, encoding?: string | WriteCallback, callback?: WriteCallback) => boolean {
+  return (chunk, encoding, callback) => {
+    capture(stream, textOf(chunk));
+    // `write(chunk, callback)` and `write(chunk, encoding, callback)` are both
+    // real calls, and a caller that passed a callback is waiting for it.
+    //
+    // Deferred, because the real `Writable.write` never calls back before it
+    // returns: a caller that writes and then does something on the next line
+    // has that line run first, and one whose callback ran inline would see the
+    // two in the other order. `queueMicrotask` rather than `process.nextTick`
+    // so this holds on every host uf supports.
+    const done = typeof encoding === "function" ? encoding : callback;
+    if (done != null) {
+      queueMicrotask(done);
+    }
+    // The real method returns whether the stream has room for more. Nothing is
+    // buffered here, so it always has — and a caller told otherwise would wait
+    // for a `drain` that never comes.
+    return true;
+  };
+}
+
+/**
+ * Route everything a test prints to `to` instead of to the process's streams,
+ * and return the real `process.stdout.write` that was replaced.
+ *
+ * The caller gets the raw stream because the caller is the protocol, and a
+ * protocol sharing its stream with the code it reports on is the bug this
+ * module exists for. Handing it back from here rather than letting the caller
+ * read it first is what makes "taken before anything could have replaced it"
+ * true by construction.
+ *
+ * Installed once, for the life of the worker: a worker runs many files, and
+ * restoring the real methods between them would leave a window in which a
+ * straggling `setTimeout` from the previous file writes into the protocol.
+ */
+export function install(to: OutputSink): (chunk: string) => void {
+  const global = host();
+  const already = raw;
+  if (already != null) {
+    return already;
+  }
+  const stdout = global.process.stdout;
+  const real = stdout.write;
+  const protocol = (chunk: string) => {
+    real.call(stdout, chunk);
+  };
+  raw = protocol;
+  sink = to;
+  for (const method of Object.keys(CONSOLE_STREAMS)) {
+    const stream = CONSOLE_STREAMS[method];
+    global.console[method] = (...args: $ReadOnlyArray<mixed>) => {
+      capture(stream, `${formatArguments(args)}\n`);
+    };
+  }
+  global.console.trace = (...args: $ReadOnlyArray<mixed>) => {
+    // `console.trace` is a message *and* the stack under it, which is the
+    // whole reason to call it rather than `console.error`. `Error.stack`
+    // opens with `Trace: <message>`, so the trace Node prints is that string
+    // with this module's own frames taken off it.
+    const error = new Error(formatArguments(args));
+    error.name = "Trace";
+    capture("stderr", `${userFrames(error.stack) ?? `Trace: ${error.message}`}\n`);
+  };
+
+  global.process.stdout.write = writer("stdout");
+  global.process.stderr.write = writer("stderr");
+  return protocol;
+}
+
+/**
+ * Say which case is running, so what it prints can be named.
+ *
+ * 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.
+ */
+export function enterTest(name: string): void {
+  current = name;
+}
+
+/** Say that no case is running. */
+export function exitTest(): void {
+  current = null;
+}
+
+/** Start one file's output budget over, with no case running. */
+export function startFile(): void {
+  captured = 0;
+  stopped = false;
+  current = null;
+}

package/internal/registry.js

@@ -32,27 +32,27 @@ export type Modifier = "none" | "only" | "skip" | "todo";
 
 /** One registered test case. */
 export type Case = {|
-  +kind: "test",
-  +name: string,
-  +body: Body | null,
-  +modifier: Modifier,
-  +timeoutMs: number | null,
-  +line: number,
-  +column: number,
+  readonly kind: "test",
+  readonly name: string,
+  readonly body: Body | null,
+  readonly modifier: Modifier,
+  readonly timeoutMs: number | null,
+  readonly line: number,
+  readonly column: number,
 |};
 
 /** One `describe` and everything inside it. */
 export type Suite = {|
-  +kind: "suite",
-  +name: string,
-  +modifier: Modifier,
-  +children: Array<Suite | Case>,
-  +beforeAll: Array<Body>,
-  +afterAll: Array<Body>,
-  +beforeEach: Array<Body>,
-  +afterEach: Array<Body>,
-  +line: number,
-  +column: number,
+  readonly kind: "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 line: number,
+  readonly column: number,
 |};
 
 function suite(name: string, modifier: Modifier, line: number, column: number): Suite {
@@ -101,7 +101,7 @@ export function collected(): Suite {
  * not in a shape we understand, the position is `0`, which every consumer
  * treats as "unknown" rather than as line one.
  */
-function callSite(): {| +line: number, +column: number |} {
+function callSite(): {| readonly line: number, readonly column: number |} {
   return firstUserSite(new Error("position").stack) ?? { line: 0, column: 0 };
 }
 
@@ -118,7 +118,12 @@ function addSuite(name: string, body: Body, modifier: Modifier): void {
   }
 }
 
-function addCase(name: string, body: Body | null, modifier: Modifier, timeoutMs: number | null): void {
+function addCase(
+  name: string,
+  body: Body | null,
+  modifier: Modifier,
+  timeoutMs: number | null,
+): void {
   const position = callSite();
   current.children.push({
     kind: "test",
@@ -132,7 +137,7 @@ function addCase(name: string, body: Body | null, modifier: Modifier, timeoutMs:
 }
 
 /** Options a single test may carry. */
-export type TestOptions = {| +timeout?: number |};
+export type TestOptions = {| readonly timeout?: number |};
 
 /**
  * The `describe` API, and its modifiers.
@@ -155,13 +160,11 @@ function suiteApi(): $FlowFixMe {
   api.todo = (name: string, body?: Body) => {
     addSuite(name, body ?? (() => {}), "todo");
   };
-  api.each =
-    (table: $ReadOnlyArray<mixed>) =>
-    (name: string, body: (row: mixed) => mixed) => {
-      for (const row of table) {
-        addSuite(formatRow(name, row), () => body(row), "none");
-      }
-    };
+  api.each = (table: $ReadOnlyArray<mixed>) => (name: string, body: (row: mixed) => mixed) => {
+    for (const row of table) {
+      addSuite(formatRow(name, row), () => body(row), "none");
+    }
+  };
   return api;
 }