@uniflowed/test 0.0.0-alpha.34 → 0.0.0-alpha.37

package/bun/index.js

@@ -0,0 +1,305 @@
+// @noflow
+//
+// Plain JavaScript: `bun:test` has no Flow library definition, and the only
+// thing that ever imports this is a `bun test` that `uf test` started.
+//
+// `@uniflowed/test`, when the suite is run by `bun test`.
+//
+// A project that writes `test: { runner: "bun" }` in `uf.config.js` has its
+// suite run by `bun test` instead of uf's own runner, and its test files do not
+// change: they still import `@uniflowed/test`. `uf test` starts Bun with the
+// `uniflowed-bun-test` export condition, and this package's `exports` sends
+// `@uniflowed/test` here under that condition and to `../index.js` under every
+// other. uf's own runner never sets it, on Node or on Bun, so the only process
+// that meets this file is one `uf test` started to hand a suite to Bun.
+//
+// # Why a condition rather than a plugin
+//
+// A `Bun.plugin` `onResolve` is not consulted for a bare specifier that
+// resolves to an installed package, and `@uniflowed/test` is installed in every
+// project that uses it. Tried on Bun 1.3.13, the test file imported uf's real
+// API, registered its cases where Bun could not see them, and `bun test`
+// printed "Ran 0 tests across 1 file" and exited 0 — a green run over a suite
+// that ran nothing. Resolution is the one place the choice is made before a
+// test file's imports run. See ubugeeei-prod/uf#942.
+//
+// # What maps, and what refuses
+//
+// The registration API, the hooks and `expect` are Bun's own, with the
+// modifiers both runners give them: `.only`, `.skip`, `.todo` and `.each`
+// (whose `%s %j %d %i` placeholders both runners format). `fn`, `spyOn`, and
+// the `uft` members Bun has an equivalent for — the fake clock and the mock
+// resets — are Bun's. uf's host-agnostic helpers are uf's: `uft.waitFor` and
+// `uft.waitUntil` poll with `setTimeout` under either runner, `uft.mocked` is
+// the identity function, and `equals` and `render` are pure.
+//
+// Everything else raises `UnsupportedError` at the moment it is used, naming
+// what was called and why there is nothing here to give it — never an
+// approximation that would report a different result:
+//
+// * `it.skipBecause`: Bun's skip carries no reason into its report, and a skip
+//   whose reason quietly disappears is what `skipBecause` exists to prevent.
+// * uf's DOM matchers and `toHaveNoAxeViolations`: Bun's `expect` has none.
+// * `uft.stubEnv`, `uft.stubGlobal` and their `unstubAll` pairs: uf puts a stub
+//   back before the next file, and `bun test` runs every file in one process
+//   where nothing would.
+// * Module mocking: Bun's `mock.module` rewrites modules that have already
+//   imported the real one, which is a different promise from `uft.mock`'s.
+// * `uft.advanceTimersByTimeAsync`: Bun's fake clock has no asynchronous
+//   advance, and flushing microtasks between timers is the whole of what it
+//   promises.
+// * `AssertionError` and `RunawayTimersError`: Bun throws errors of its own, so
+//   a test comparing a failure against uf's class would be comparing it against
+//   a class nothing throws.
+
+import * as bun from "bun:test";
+
+import { equals, render } from "../internal/equality.js";
+import { mocked, waitFor, waitUntil } from "../internal/namespace.js";
+import { DEFAULT_TIMEOUT_MS, NAME_SEPARATOR } from "../internal/run.js";
+import { UnsupportedError } from "../internal/unsupported.js";
+
+export { UnsupportedError, equals, render, DEFAULT_TIMEOUT_MS, NAME_SEPARATOR };
+export { afterAll, afterEach, beforeAll, beforeEach } from "bun:test";
+
+/** What every refusal here says about where the suite is running. */
+const UNDER_BUN = "the suite is being run by `bun test` (`test.runner` in uf.config.js)";
+
+/**
+ * The error for something that is not a `uft` member.
+ *
+ * Still an `UnsupportedError`, because that is the class a test catches;
+ * only the message changes, since `UnsupportedError`'s is written for `uft`
+ * members and `it.skipBecause` or a matcher is not one.
+ */
+class RunnerUnsupportedError extends UnsupportedError {
+  constructor(binding, reason) {
+    super(binding, reason);
+    this.message = `${binding} is not available: ${reason}`;
+  }
+}
+
+/** A function that refuses, for a binding with no equivalent under Bun. */
+function refusing(binding, reason, Refusal = RunnerUnsupportedError) {
+  return () => {
+    throw new Refusal(binding, `${UNDER_BUN}, and ${reason}`);
+  };
+}
+
+/** A class that refuses to be constructed or compared against. */
+function refusingClass(name, reason) {
+  const refuse = refusing(name, reason);
+  return class {
+    constructor() {
+      refuse();
+    }
+
+    static [Symbol.hasInstance]() {
+      return refuse();
+    }
+  };
+}
+
+/** The placeholders uf's `.each` substitutes a row into. */
+const ROW_TOKEN = /%[sjdi]/g;
+
+/**
+ * A row's case name, written the way uf's own runner writes it.
+ *
+ * Bun's `.each` differs from uf's twice over: it spreads an array row into the
+ * body's arguments where uf hands the body the row whole, and its JUnit report
+ * records the name with the placeholder still in it (`formats row %s`, once
+ * per row). A suite whose cases are named differently by the two runners is a
+ * suite whose results cannot be compared between them, so `.each` here is
+ * uf's, registering one case per row through Bun's plain registration.
+ * Mirrors `formatRow` in `../internal/registry.js`.
+ */
+function formatRow(name, row) {
+  const values = Array.isArray(row) ? row : [row];
+  let index = 0;
+  return name.replace(ROW_TOKEN, (token) => {
+    const value = values[index];
+    index += 1;
+    return token === "%j" ? (JSON.stringify(value) ?? "undefined") : String(value);
+  });
+}
+
+/**
+ * One of uf's registration functions, forwarding to Bun's.
+ *
+ * Forwarded call by call rather than re-exported, so that a modifier uf has
+ * and Bun does not — `it.skipBecause` — can be attached without reaching into
+ * Bun's own function object.
+ */
+function registration(bunApi) {
+  const api = (...args) => bunApi(...args);
+  api.only = (...args) => bunApi.only(...args);
+  api.skip = (...args) => bunApi.skip(...args);
+  api.todo = (...args) => bunApi.todo(...args);
+  api.each = (table) => (name, body, options) => {
+    for (const row of table) {
+      bunApi(formatRow(name, row), () => body(row), options);
+    }
+  };
+  return api;
+}
+
+export const describe = registration(bun.describe);
+export const it = registration(bun.it);
+it.skipBecause = refusing(
+  "it.skipBecause",
+  'Bun\'s skip carries no reason into its report; write `it.skip`, or run this file with `runner: "uf"`',
+);
+export const test = it;
+
+/**
+ * `bench`, which `bun:test` has no counterpart for.
+ *
+ * Its modifiers refuse too, by name, rather than failing on `undefined`.
+ */
+const refuseBench = refusing(
+  "bench",
+  '`bun:test` has no benchmarks; run them with `runner: "uf"` and `uf test --bench`',
+);
+export const bench = (..._args) => refuseBench();
+bench.only = refuseBench;
+bench.skip = refuseBench;
+bench.todo = refuseBench;
+
+/** uf's matchers that Bun's `expect` has no counterpart for. */
+const MATCHERS_BUN_LACKS = [
+  "toBeChecked",
+  "toBeDisabled",
+  "toBeEnabled",
+  "toBeInTheDocument",
+  "toBeRequired",
+  "toBeVisible",
+  "toHaveAttribute",
+  "toHaveClass",
+  "toHaveFocus",
+  "toHaveTextContent",
+  "toHaveValue",
+  "toHaveNoAxeViolations",
+];
+
+bun.expect.extend(
+  Object.fromEntries(
+    MATCHERS_BUN_LACKS.map((matcher) => [
+      matcher,
+      refusing(
+        `expect(…).${matcher}`,
+        "Bun's `expect` has no such matcher; assert on the element's properties directly, or run this file with `runner: \"uf\"`",
+      ),
+    ]),
+  ),
+);
+
+/**
+ * uf's snapshot matchers.
+ *
+ * Bun has matchers by these names, and they are still not the same matchers:
+ * both runners write `__snapshots__/<file>.snap` in Jest's format, but each
+ * keys an entry by its own spelling of the test's name and serialises the value
+ * its own way. Passed through, a suite recorded by uf would either fail against
+ * its own snapshots or quietly write a second set beside them — and a snapshot
+ * that was rewritten rather than compared is the failure snapshots exist to
+ * catch.
+ */
+const SNAPSHOT_MATCHERS = ["toMatchSnapshot", "toMatchInlineSnapshot"];
+
+bun.expect.extend(
+  Object.fromEntries(
+    SNAPSHOT_MATCHERS.map((matcher) => [
+      matcher,
+      refusing(
+        `expect(…).${matcher}`,
+        'uf and Bun key and serialise snapshots differently, so this would compare against — or rewrite — a snapshot uf did not write; run snapshot tests with `runner: "uf"`',
+      ),
+    ]),
+  ),
+);
+
+export const expect = bun.expect;
+
+export const fn = (...args) => bun.jest.fn(...args);
+export const spyOn = (...args) => bun.spyOn(...args);
+
+export const AssertionError = refusingClass(
+  "AssertionError",
+  "Bun throws its own assertion errors, so nothing a failure throws is an instance of uf's",
+);
+export const RunawayTimersError = refusingClass(
+  "RunawayTimersError",
+  "Bun's fake clock throws its own error for a timer loop that never ends",
+);
+
+/** A `uft` member with no equivalent under Bun. */
+const refusingMember = (member, reason) => refusing(member, reason, UnsupportedError);
+
+const MODULE_MOCKING =
+  "Bun's `mock.module` rewrites modules that have already imported the real one, which is a different promise from `uft.mock`'s (see guide/testing, \"Which hosts\")";
+
+const STUBS =
+  "uf puts a stub back before the next file, and `bun test` runs every file in one process where nothing would";
+
+export const uft = Object.freeze({
+  fn,
+  spyOn,
+  mocked,
+
+  clearAllMocks: () => bun.jest.clearAllMocks(),
+  resetAllMocks: () => bun.jest.resetAllMocks(),
+  restoreAllMocks: () => bun.jest.restoreAllMocks(),
+
+  stubEnv: refusingMember("stubEnv", STUBS),
+  unstubAllEnvs: refusingMember("unstubAllEnvs", STUBS),
+  stubGlobal: refusingMember("stubGlobal", STUBS),
+  unstubAllGlobals: refusingMember("unstubAllGlobals", STUBS),
+
+  waitFor,
+  waitUntil,
+
+  useFakeTimers: () => {
+    bun.jest.useFakeTimers();
+  },
+  useRealTimers: () => {
+    bun.jest.useRealTimers();
+  },
+  isFakeTimers: () => bun.jest.isFakeTimers(),
+  advanceTimersByTime: (milliseconds) => {
+    bun.jest.advanceTimersByTime(milliseconds);
+  },
+  advanceTimersByTimeAsync: refusingMember(
+    "advanceTimersByTimeAsync",
+    "Bun's fake clock has no asynchronous advance; await between `uft.advanceTimersByTime` calls instead",
+  ),
+  advanceTimersToNextTimer: (steps) => {
+    bun.jest.advanceTimersToNextTimer(steps);
+  },
+  runAllTimers: () => {
+    bun.jest.runAllTimers();
+  },
+  runOnlyPendingTimers: () => {
+    bun.jest.runOnlyPendingTimers();
+  },
+  getTimerCount: () => bun.jest.getTimerCount(),
+  // uf's clock only moves while it is faked, and a time set before
+  // `useFakeTimers` is forgotten when the clock is installed. Bun's
+  // `setSystemTime` moves the real `Date` whether or not anything is faked, so
+  // it is only forwarded while Bun's clock is faked — outside that it does
+  // what uf's does, which is nothing a test can observe.
+  setSystemTime: (time) => {
+    if (bun.jest.isFakeTimers()) {
+      bun.setSystemTime(time);
+    }
+  },
+  getMockedSystemTime: () => (bun.jest.isFakeTimers() ? new Date() : null),
+
+  mock: refusingMember("mock", MODULE_MOCKING),
+  doMock: refusingMember("doMock", MODULE_MOCKING),
+  unmock: refusingMember("unmock", MODULE_MOCKING),
+  doUnmock: refusingMember("doUnmock", MODULE_MOCKING),
+  importActual: refusingMember("importActual", MODULE_MOCKING),
+  importMock: refusingMember("importMock", MODULE_MOCKING),
+  resetModules: refusingMember("resetModules", MODULE_MOCKING),
+});

package/index.js

@@ -14,7 +14,14 @@
 
 export type { Expect, Expectation, Matchers } from "./internal/expect.js";
 export type { InSourceTests } from "./in-source.js";
-export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
+export type {
+  BenchOptions,
+  Body as TestBody,
+  Case,
+  Modifier,
+  Suite,
+  TestOptions,
+} from "./internal/registry.js";
 export type { ModuleFactory, ModuleNamespace } from "./internal/modules.js";
 export type { Uft } from "./internal/namespace.js";
 export type { Outcome, Result, RunOptions } from "./internal/run.js";
@@ -27,6 +34,7 @@ export {
   afterEach,
   beforeAll,
   beforeEach,
+  bench,
   describe,
   it,
   test,

package/internal/axe.js

@@ -207,6 +207,87 @@ function excerpt(html: string): string {
   return line.length > MAX_NODE_CHARS ? `${line.slice(0, MAX_NODE_CHARS)}…` : line;
 }
 
+/**
+ * The audit this process started last, settled or not.
+ *
+ * axe-core runs one audit at a time per process and refuses a second outright
+ * ("Axe is already running") rather than queueing it. One file never starts two
+ * on purpose, but a worker serves many files: a case that timed out in the
+ * middle of an audit leaves that audit running, and the next file's first audit
+ * used to fail on it — reported under a file that had done nothing wrong.
+ */
+let running: Promise<mixed> = Promise.resolve();
+
+/**
+ * Run `audit` once the audit already running has settled, however it settles.
+ *
+ * Waiting rather than failing is safe because the audit being waited on always
+ * ends — axe-core walks a finite tree — and a case that waits too long is still
+ * bounded by its own timeout.
+ */
+function afterTheAuditRunning<T>(audit: () => Promise<T>): Promise<T> {
+  const turn = running.then(audit, audit);
+  running = turn.then(
+    () => undefined,
+    () => undefined,
+  );
+  return turn;
+}
+
+/** How long to wait between looks at an audit this module did not start. */
+const FOREIGN_AUDIT_POLL_MS = 10;
+
+/** How long an audit this module did not start may hold axe-core. */
+const FOREIGN_AUDIT_LIMIT_MS = 10000;
+
+// The timer and the clock as they were when this module loaded, so a file that
+// fakes timers cannot stall a wait for a real audit to end.
+const pause: typeof setTimeout = setTimeout;
+const now: () => number = Date.now.bind(Date);
+
+/**
+ * Whether axe-core refused to start because an audit is already running.
+ *
+ * `running` queues every audit this module starts, so a refusal means an audit
+ * started somewhere else. `uf dev`'s overlay runs axe-core itself, and stopping
+ * the overlay cannot recall an audit already walking the page: its own test can
+ * leave one finishing into the next file in the worker.
+ */
+function isAlreadyRunning(error: mixed): boolean {
+  return error instanceof Error && error.message.startsWith("Axe is already running");
+}
+
+/**
+ * Run the audit once axe-core is free of an audit this module did not start.
+ *
+ * Looks again every `FOREIGN_AUDIT_POLL_MS` until axe-core takes it, and after
+ * `FOREIGN_AUDIT_LIMIT_MS` says what held the engine rather than waiting on an
+ * audit that is not going to end.
+ */
+function runOnceAxeIsFree(
+  axe: $FlowFixMe,
+  node: mixed,
+  options: mixed,
+  since: number = now(),
+): Promise<mixed> {
+  return Promise.resolve()
+    .then(() => axe.run(node, options))
+    .catch((error: mixed) => {
+      if (!isAlreadyRunning(error)) {
+        throw error;
+      }
+      if (now() - since >= FOREIGN_AUDIT_LIMIT_MS) {
+        throw new Error(
+          "axe-core has been running an audit uf did not start for ten seconds, such as " +
+            "`uf dev`'s overlay or a direct `axe.run`; this assertion could not start its own.",
+        );
+      }
+      return new Promise((resolve) => {
+        pause(resolve, FOREIGN_AUDIT_POLL_MS);
+      }).then(() => runOnceAxeIsFree(axe, node, options, since));
+    });
+}
+
 /**
  * Audit `node` and report what it found, weakest results already dropped.
  *
@@ -229,7 +310,9 @@ export async function auditElement(
   }
   const axe = await axeEngine();
   const options = resolveOptions(overrides);
-  const results = await axe.run(node, axeRunOptions(options));
+  const results = await afterTheAuditRunning(() =>
+    runOnceAxeIsFree(axe, node, axeRunOptions(options)),
+  );
   const found: Array<AxeViolation> = [];
   for (const raw of arrayAt(results, "violations")) {
     const violation: AxeViolation = {

package/internal/isolation.js

@@ -8,10 +8,10 @@
 // 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:
+// That second list is what this module is. It has been discovered four times,
+// 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;
@@ -20,7 +20,11 @@
 //     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.
+//     the page" found six;
+//   * ubugeeei-prod/uf#944, the window around that body: a `matchMedia` a file
+//     removed, and the document's `FormData` left in place of Node's. That one is not on the list below, because this package does not
+//     make the window — `@uniflowed/react-testing` does, and registers how to
+//     put it back (see `registeredElsewhere`).
 //
 // 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
@@ -168,6 +172,37 @@ function restoreDocument(): void {
   }
 }
 
+/**
+ * Where other packages register process-wide state of their own.
+ *
+ * A package this one does not depend on can still install something a file
+ * changes and the next file reads: `@uniflowed/react-testing` installs a window
+ * on the first render and keeps it for the process. Only that package knows
+ * what the window looked like when it made it, so it registers how to put it
+ * back — a name for the message below, and a function — in a `Map` under this
+ * symbol, and every entry runs after the list above.
+ *
+ * A symbol from the global registry rather than an export, so the package that
+ * registers needs no import of this one: under another runner the entry is
+ * never read and costs nothing.
+ */
+const SHARED_STATE: symbol = Symbol.for("@uniflowed/test/shared-state");
+
+/** Every entry another package registered, as this module's own entries are shaped. */
+function registeredElsewhere(): $ReadOnlyArray<Shared> {
+  const registry: mixed = Reflect.get(globalThis, SHARED_STATE);
+  if (!(registry instanceof Map)) {
+    return [];
+  }
+  const entries: Array<Shared> = [];
+  for (const [what, restore] of registry) {
+    if (typeof what === "string" && typeof restore === "function") {
+      entries.push({ what, restore: () => void restore() });
+    }
+  }
+  return entries;
+}
+
 /**
  * Put back everything the file that just ran may have changed.
  *
@@ -185,7 +220,7 @@ function restoreDocument(): void {
  */
 export function restoreSharedState(): void {
   let failure: { readonly what: string, readonly thrown: mixed } | null = null;
-  for (const shared of SHARED) {
+  for (const shared of [...SHARED, ...registeredElsewhere()]) {
     try {
       shared.restore();
     } catch (thrown) {

package/internal/registry.js

@@ -30,14 +30,29 @@ export type Body = () => mixed | Promise<mixed>;
 /** The suffix written on a registration call. */
 export type Modifier = "none" | "only" | "skip" | "todo";
 
-/** One registered test case. */
+/**
+ * How a benchmark runs under `uf test --bench`.
+ *
+ * `warmup` calls are made and their times thrown away, then `iterations` calls
+ * are each timed. `timeout` is the budget for one call, in milliseconds, and
+ * the benchmark as a whole is held to that budget once per call.
+ */
+export type BenchOptions = {|
+  readonly warmup?: number,
+  readonly iterations?: number,
+  readonly timeout?: number,
+|};
+
+/** One registered test case, or one benchmark. */
 export type Case = {|
-  readonly kind: "test",
+  readonly kind: "test" | "bench",
   readonly name: string,
   readonly body: Body | null,
   readonly modifier: Modifier,
   readonly skipReason: string | null,
   readonly timeoutMs: number | null,
+  /** How to run it, for a benchmark; `null` for a test. */
+  readonly bench: BenchOptions | null,
   readonly line: number,
   readonly column: number,
 |};
@@ -125,15 +140,17 @@ function addCase(
   modifier: Modifier,
   timeoutMs: number | null,
   skipReason: string | null = null,
+  bench: BenchOptions | null = null,
 ): void {
   const position = callSite();
   current.children.push({
-    kind: "test",
+    kind: bench == null ? "test" : "bench",
     name,
     body,
     modifier,
     skipReason,
     timeoutMs,
+    bench,
     line: position.line,
     column: position.column,
   });
@@ -217,6 +234,34 @@ export const it: $FlowFixMe = caseApi();
 /** `test` is `it`, for people who write it that way. */
 export const test: $FlowFixMe = it;
 
+/** The `bench` API, and its modifiers. See [`suiteApi`] for the shape. */
+function benchApi(): $FlowFixMe {
+  const api: $FlowFixMe = (name: string, body: Body, options?: BenchOptions) => {
+    addCase(name, body, "none", options?.timeout ?? null, null, options ?? {});
+  };
+  api.only = (name: string, body: Body, options?: BenchOptions) => {
+    addCase(name, body, "only", options?.timeout ?? null, null, options ?? {});
+  };
+  api.skip = (name: string, body?: Body) => {
+    addCase(name, body ?? null, "skip", null, null, {});
+  };
+  api.todo = (name: string) => {
+    addCase(name, null, "todo", null, null, {});
+  };
+  return api;
+}
+
+/**
+ * Register one benchmark.
+ *
+ * `uf test` reports a benchmark as skipped, so a suite does not pay for timing
+ * one, and `uf test --bench` runs the benchmarks in place of the tests and
+ * reports how long each call took. `bench.only`, `bench.skip` and `bench.todo`
+ * do what `it`'s do. See [`BenchOptions`] for `warmup`, `iterations` and
+ * `timeout`.
+ */
+export const bench: $FlowFixMe = benchApi();
+
 /**
  * Substitute a row into a name, the way every runner spells it: `%s` for the
  * value, `%j` for its JSON.

package/internal/run.js

@@ -13,11 +13,18 @@ import * as output from "./output.js";
 import * as snapshot from "./snapshot.js";
 import { AssertionError } from "./expect.js";
 import { type Site, firstUserSite, siteInFile, userFrames } from "./frames.js";
-import { type Body, type Case, type Suite, collected } from "./registry.js";
+import { type BenchOptions, type Body, type Case, type Suite, collected } from "./registry.js";
 
 /** How one case ended. */
 export type Outcome =
-  | {| readonly status: "passed" |}
+  | {|
+      readonly status: "passed",
+      /**
+       * One timing per measured call, in whole microseconds, for a benchmark
+       * run under `uf test --bench`.
+       */
+      readonly samples?: $ReadOnlyArray<number>,
+    |}
   | {|
       readonly status: "failed",
       readonly message: string,
@@ -29,7 +36,7 @@ export type Outcome =
     |}
   | {|
       readonly status: "skipped",
-      readonly reason: "explicit" | "not-only" | "filtered",
+      readonly reason: "explicit" | "not-only" | "filtered" | "bench" | "not-bench",
       readonly message?: string | null,
     |}
   | {| readonly status: "todo" |};
@@ -56,11 +63,31 @@ export type RunOptions = {|
    * which file that is — a test's name alone does not locate it.
    */
   readonly file?: string,
+  /**
+   * Run the benchmarks and report the tests skipped, rather than the other way
+   * round. `uf test --bench` sets it.
+   */
+  readonly bench?: boolean,
 |};
 
 /** Default budget for one case, matching what most runners use. */
 export const DEFAULT_TIMEOUT_MS: number = 5000;
 
+/** Calls a benchmark makes and throws away before it times any, unless it says. */
+export const DEFAULT_BENCH_WARMUP: number = 5;
+
+/** Timed calls a benchmark makes, unless it says. */
+export const DEFAULT_BENCH_ITERATIONS: number = 50;
+
+/** Most timed calls one benchmark may ask for, and most samples `uf` keeps. */
+export const MAX_BENCH_ITERATIONS: number = 100000;
+
+/** Most untimed calls one benchmark may ask for first. */
+export const MAX_BENCH_WARMUP: number = 10000;
+
+/** The longest delay `setTimeout` honours; past it, the timer fires at once. */
+const MAX_TIMER_MS = 2147483647;
+
 /** The separator between a suite's name and its child's. */
 export const NAME_SEPARATOR: string = " > ";
 
@@ -76,7 +103,9 @@ function fullName(path: $ReadOnlyArray<string>): string {
  */
 function hasOnly(node: Suite | Case, inherited: boolean): boolean {
   const marked = inherited || node.modifier === "only";
-  if (node.kind === "test") {
+  // A benchmark is a case like a test: `bench.only` restricts a file as
+  // `it.only` does.
+  if (node.kind !== "suite") {
     return marked;
   }
   return node.children.some((child) => hasOnly(child, marked));
@@ -214,9 +243,19 @@ async function runCase(
     report({ status: "skipped", reason: "filtered" });
     return true;
   }
+  // A run is the tests or the benchmarks, never both. A benchmark timed inside
+  // an ordinary run would slow every suite that has one, beside workers busy
+  // with other files; a test inside a run of benchmarks would be timed with
+  // them.
+  const benchmark = test.kind === "bench";
+  if (benchmark !== (options.bench === true)) {
+    report({ status: "skipped", reason: benchmark ? "bench" : "not-bench" });
+    return true;
+  }
 
   const timeoutMs = test.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   let outcome: Outcome = { status: "passed" };
+  let samples: $ReadOnlyArray<number> | null = null;
   // 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
@@ -231,7 +270,11 @@ async function runCase(
       for (const hook of context.beforeEach) {
         await withTimeout(hook, timeoutMs);
       }
-      await withTimeout(body, timeoutMs);
+      if (benchmark) {
+        samples = await measure(body, test.bench, timeoutMs);
+      } else {
+        await withTimeout(body, timeoutMs);
+      }
     } catch (thrown) {
       outcome = failure(thrown, options.file ?? null);
     }
@@ -252,10 +295,74 @@ async function runCase(
   // 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);
+  report(outcome.status === "passed" && samples != null ? { status: "passed", samples } : outcome);
   return outcome.status !== "failed";
 }
 
+/**
+ * Time a benchmark's body: `warmup` calls thrown away, then `iterations` timed.
+ *
+ * The body is called directly and awaited, with nothing else between the two
+ * readings of the clock: a timer set around every call would be timed with
+ * it, and on a body that takes microseconds that is most of the number. The
+ * budget is held around the whole loop instead, at one call's budget per
+ * call, so a benchmark that hangs still fails rather than holding the worker.
+ */
+async function measure(
+  body: Body,
+  options: BenchOptions | null,
+  timeoutMs: number,
+): Promise<$ReadOnlyArray<number>> {
+  const warmup = count("warmup", options?.warmup, DEFAULT_BENCH_WARMUP, 0, MAX_BENCH_WARMUP);
+  const iterations = count(
+    "iterations",
+    options?.iterations,
+    DEFAULT_BENCH_ITERATIONS,
+    1,
+    MAX_BENCH_ITERATIONS,
+  );
+  const rounds = warmup + iterations;
+  const samples: Array<number> = [];
+  await withTimeout(
+    async () => {
+      for (let round = 0; round < rounds; round += 1) {
+        const started = performance.now();
+        await body();
+        if (round >= warmup) {
+          samples.push(Math.round((performance.now() - started) * 1000));
+        }
+      }
+    },
+    Math.min(timeoutMs * rounds, MAX_TIMER_MS),
+  );
+  return samples;
+}
+
+/**
+ * A benchmark option that has to be a whole number from `least` to `most`.
+ *
+ * Refused rather than clamped: `iterations: 0` or `warmup: 1e9` is a mistake,
+ * and a benchmark quietly run some other number of times reports numbers
+ * about a run nobody asked for.
+ */
+function count(
+  option: string,
+  value: ?number,
+  fallback: number,
+  least: number,
+  most: number,
+): number {
+  if (value == null) {
+    return fallback;
+  }
+  if (!Number.isInteger(value) || value < least || value > most) {
+    throw new Error(
+      `bench \`${option}\` has to be a whole number from ${least} to ${most}, and was ${String(value)}`,
+    );
+  }
+  return value;
+}
+
 /**
  * Walk one suite, running what it contains.
  *
@@ -306,13 +413,16 @@ async function runSuite(
     if (state.bail) {
       break;
     }
-    if (child.kind === "test") {
+    if (child.kind !== "suite") {
       const willRun =
         !inner.skipped &&
         child.modifier !== "skip" &&
         child.modifier !== "todo" &&
         child.body != null &&
-        (!onlyMode || inner.onlyPath || child.modifier === "only");
+        (!onlyMode || inner.onlyPath || child.modifier === "only") &&
+        // A benchmark in a run of the tests, or a test in a run of the
+        // benchmarks, is reported skipped and sets nothing up.
+        (child.kind === "bench") === (options.bench === true);
       if (willRun) {
         try {
           await setUpOnce();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.0.0-alpha.34",
+  "version": "0.0.0-alpha.37",
   "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",
@@ -11,7 +11,10 @@
     "directory": "packages/test"
   },
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "uniflowed-bun-test": "./bun/index.js",
+      "default": "./index.js"
+    },
     "./in-source": "./in-source.js",
     "./worker": "./worker.js",
     "./browser-worker": "./browser-worker.js",
@@ -19,6 +22,7 @@
   },
   "files": [
     "browser-worker.js",
+    "bun",
     "in-source.js",
     "index.js",
     "internal",
@@ -26,7 +30,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.0.0-alpha.34"
+    "@uniflowed/host": "0.0.0-alpha.37"
   },
   "peerDependencies": {
     "axe-core": ">=4"

package/worker.js

@@ -58,26 +58,19 @@ import { installInSourceTests } from "./in-source.js";
 import { restoreSharedState } from "./internal/isolation.js";
 import { run } from "./internal/run.js";
 
-// `process` is imported rather than read off the global, and then put *on*
-// the global, because one host in three does not have it there.
+// `process` is imported rather than read off the global because this file is
+// the process entry point, and an entry point that names what it depends on is
+// one a reader does not have to trust.
 //
-// Deno exposes the whole object as `node:process` and nothing as
-// `globalThis.process` — `crates/uf_cli/tests/deno_host.rs` starts a real one
-// and asserts both halves. Every module this worker reaches that wants the
-// process reaches for the global: `internal/output.js` replaces
-// `process.stdout.write` so a test's printing cannot land in the middle of the
-// protocol, `internal/namespace.js` reads `process.env` for `stubEnv`, and
-// `internal/axe.js` reads `UF_AXE` from it. Threading an import through all
-// three would put a `node:` specifier into modules a browser build resolves,
-// for a difference no other host has.
-//
-// So the entry point installs it, once, before anything below runs. `??=`
-// rather than `=`: on Node and Bun the global is already the real object and
-// this must not replace it with a second view of the same thing.
-//
-// It is a shim of the host, in the one file that is a process entry point, and
-// it stops here — nothing else in `@uniflowed/test` may do this.
-globalThis.process ??= process;
+// It used to be put *on* the global as well. Deno 1.x exposed the object as
+// `node:process` and nothing as `globalThis.process`, and every module this
+// worker reaches that wants the process reads the global: `internal/output.js`
+// replaces `process.stdout.write`, `internal/namespace.js` reads
+// `process.env` for `stubEnv`, and `internal/axe.js` reads `UF_AXE`. The Deno
+// uf starts is 2.8 or newer — `@uniflowed/host/deno-preload` is built on that
+// release's `registerHooks`, and `uf test` refuses anything older — and Deno 2
+// 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. */
 type Request = {|
@@ -159,6 +152,17 @@ function write(event: { readonly [string]: mixed }): void {
  * 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.
  */
+/**
+ * Whether this is a run of the benchmarks, `uf test --bench`.
+ *
+ * Read from the environment, as snapshot updates are: it is a property of the
+ * 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;
+  return value != null && value !== "" && value !== "0";
+}
+
 async function runFile(request: Request, generation: number): Promise<void> {
   const started = performance.now();
   // Everything the previous file changed and this package shares with it goes
@@ -231,7 +235,12 @@ async function runImportedFile(
   try {
     const absolute = fileURLToPath(pathToFileURL(request.file).href);
     await run(
-      { filter: request.filter ?? null, timeoutMs: request.timeoutMs, file: absolute },
+      {
+        filter: request.filter ?? null,
+        timeoutMs: request.timeoutMs,
+        file: absolute,
+        bench: benching(),
+      },
       (result) => {
         write({
           event: "test",