@uniflowed/test 0.0.0-alpha.8 → 0.1.0

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/in-source.js

@@ -0,0 +1,169 @@
+// @flow
+//
+// In-source tests: `if (import.meta.uf.test) { … }` in the file being tested.
+//
+// A three-line test for a three-line pure function does not want a file of its
+// own, an import of the thing it tests, and a path that has to be kept in step
+// with it. `import.meta.uf.test` is the block that holds it, and it is the
+// same idea as Vitest's `import.meta.vitest` for the same reason.
+//
+// # What a block looks like
+//
+//     import { expect, it } from "@uniflowed/test";
+//
+//     export function add(a: number, b: number): number {
+//       return a + b;
+//     }
+//
+//     if (import.meta.uf.test) {
+//       it("adds", () => {
+//         expect(add(1, 2)).toBe(3);
+//       });
+//     }
+//
+// An ordinary import for the bindings, because that is what makes them typed:
+// Flow has no `typeof import("…")` for a library definition to use, so a
+// marker that carried the API could not be described to the checker. The
+// marker's *value* is the API anyway — `const { it } = import.meta.uf.test` is
+// what somebody arriving from Vitest writes and it works — but it is untyped,
+// and the import is the form uf recommends.
+//
+// The import costs nothing in a build. The branch folds to `if (void 0)` and
+// goes, `@uniflowed/test` declares `sideEffects: false` so the now-unused
+// import goes with it, and the package carries a `browser` field mapping the
+// six `node:` builtins its edges import at `./internal/browser/node.js` — so
+// the bundler does not even print a warning about modules it is in the middle
+// of removing.
+//
+// # What makes the block disappear
+//
+// `uf` compiles the marker away rather than leaving it to be falsy at runtime:
+// `crates/uf_transform`'s printer substitutes `void 0` for
+// `import.meta.uf.test` in every transform except the ones `uf test` asks for,
+// so `uf build` sees `if (void 0)` and the bundler removes the block. There is
+// no `import.meta.uf` at runtime, in any host, which is also why the block
+// cannot throw in a browser that never heard of uf.
+//
+// `tests/library/in-source.test.js` and `tests/library/in-source-subject.js`
+// are the block running. The other half is in `crates/uf_cli/tests/vite.rs`,
+// which builds a fixture whose block holds a string that appears nowhere else
+// and reads the emitted client bundle back looking for it — in the same file
+// the module's other marker has to be present in, because "a string is
+// missing" is only evidence when something establishes the module is not.
+//
+// # Why the marker is a call, and what it is called with
+//
+// Under `uf test` the printer substitutes
+// `globalThis.__ufInSourceTests?.(import.meta.url)`, and this module is what
+// answers it. The argument is the module asking, because a source file with an
+// in-source block is an ordinary module and is imported more than once in a
+// normal run: `uf test` imports `add.js` as the file it is running, and
+// `add.test.js` imports it again for the function. Both evaluations reach the
+// marker. Only the first is the file the run is reporting on, so only the
+// first is given the API — otherwise every in-source case would register twice
+// and the second copy would be filed under whichever test file imported it.
+
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  it,
+  test,
+} from "./internal/registry.js";
+import { fn, spyOn } from "./internal/spy.js";
+
+import type { Expect } from "./internal/expect.js";
+import type { Uft } from "./internal/namespace.js";
+import { expect } from "./internal/expect.js";
+import { uft } from "./internal/namespace.js";
+
+/**
+ * The name `uf` compiles `import.meta.uf.test` into a call on.
+ *
+ * Exported so the worker and the tests name it once; it is spelled out in `crates/uf_transform/src/print.rs` as well, and
+ * `tests/library/in-source.test.js` is what keeps the two spellings equal.
+ */
+export const IN_SOURCE_GLOBAL: "__ufInSourceTests" = "__ufInSourceTests";
+
+/**
+ * What an in-source block is handed.
+ *
+ * The subset of `@uniflowed/test` a test body needs, and deliberately not all
+ * of it: a block that wants module mocking or a snapshot is a block that has
+ * outgrown living inside the file it tests, and `import { uft } from
+ * "@uniflowed/test"` in a file of its own is the answer to that. `uft` is here
+ * anyway because spies and the fake clock are ordinary for a unit test.
+ */
+export type InSourceTests = {
+  readonly describe: typeof describe,
+  readonly it: typeof it,
+  readonly test: typeof test,
+  readonly expect: Expect,
+  readonly beforeAll: typeof beforeAll,
+  readonly beforeEach: typeof beforeEach,
+  readonly afterAll: typeof afterAll,
+  readonly afterEach: typeof afterEach,
+  readonly fn: typeof fn,
+  readonly spyOn: typeof spyOn,
+  readonly uft: Uft,
+};
+
+/**
+ * The API every in-source block in a run shares.
+ *
+ * One frozen object rather than one per file: the bindings are the module's
+ * own singletons — `it` registers into the one registry the worker resets
+ * between files — so a copy per file would only be a copy of the same
+ * references.
+ */
+const API: InSourceTests = Object.freeze({
+  describe,
+  it,
+  test,
+  expect,
+  beforeAll,
+  beforeEach,
+  afterAll,
+  afterEach,
+  fn,
+  spyOn,
+  uft,
+});
+
+/**
+ * The module URL, without whatever a host appended to it.
+ *
+ * The worker busts its import cache with `?uf-run=<generation>` so a watch
+ * rerun sees the edited file, which means the file being run reports an
+ * `import.meta.url` that its own path does not match. Comparing the part
+ * before the query is comparing the module.
+ *
+ * A hash is stripped for the same reason and never appears in practice; it
+ * costs one `indexOf` to not have to think about it again.
+ */
+function moduleUrl(url: string): string {
+  const end = url.search(/[?#]/);
+  return end === -1 ? url : url.slice(0, end);
+}
+
+/**
+ * Hand in-source blocks their API for the file `url`, and nothing to any other
+ * module.
+ *
+ * Returns the function that puts the global back as it was, which the worker
+ * calls when the file is over. Restoring rather than leaving it set is the
+ * same rule the worker applies to environment stubs and module mocks: a file
+ * may not change what the next file on this worker sees.
+ */
+export function installInSourceTests(url: string): () => void {
+  const wanted = moduleUrl(url);
+  const globals: { [string]: mixed } = globalThis as $FlowFixMe;
+  const previous = globals[IN_SOURCE_GLOBAL];
+  globals[IN_SOURCE_GLOBAL] = (asking: string): InSourceTests | void =>
+    moduleUrl(asking) === wanted ? API : undefined;
+  return () => {
+    globals[IN_SOURCE_GLOBAL] = previous;
+  };
+}

package/index.js

@@ -12,7 +12,16 @@
 //
 // The whole surface is importable from here, so a test file has one import.
 
-export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
+export type { Expect, Expectation, Matchers } from "./internal/expect.js";
+export type { InSourceTests } from "./in-source.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";
@@ -25,6 +34,7 @@ export {
   afterEach,
   beforeAll,
   beforeEach,
+  bench,
   describe,
   it,
   test,