@uniflowed/test 0.1.0 → 0.2.0

package/internal/expect.js

@@ -814,58 +814,114 @@ function isDisabled(node: Element): boolean {
  * `negated` decides which message a failing verdict raises, which is all of
  * what `.not` is.
  *
- * # Why the object is built rather than written
+ * # Why the matchers live on a prototype
  *
- * `.not` has to be reached lazily or building an expectation would build its
- * negation, which would build *its* negation, forever. A lazily installed
- * property is not something an object literal carries, so the value is
- * completed with `Object.defineProperty` after it exists — and an object
- * completed after the fact is not one Flow can check a literal against. That
- * is what this `$FlowFixMe` is, and it now covers a construction rather than a
- * published type: [`expectValue`] states the real one, and the checker holds
- * every caller to it.
+ * `expect` is called once per assertion, and building its answer used to be
+ * the largest single cost of a passing assertion: the whole verdict table and a
+ * wrapper for each of its forty-one entries, eighty-odd closures, to call one
+ * of them. On a suite of 1,000 cases and 2,000 assertions that was about a
+ * twentieth of a worker's CPU, spent on functions nobody called.
+ *
+ * So the object carries only what differs between two assertions — the value
+ * and the polarity — and every matcher is a getter on one shared prototype,
+ * built the first time `expect` is used. The getter hands back a function
+ * closed over the object it was read from, rather than being a method that
+ * reads `this`: `const { toBe } = expect(1)` and `[1, 2].forEach(expect(n).not.toBe)`
+ * keep working, because the function a destructuring or a callback receives is
+ * already bound, which is what they got when every matcher was an own closure.
+ * The table is still built per *call*, from [`verdicts`], so a matcher still
+ * sees the one received value it was asked about and nothing else.
+ *
+ * `.not` is a getter on the same prototype for the reason it always was
+ * lazy: an expectation that built its negation would build *its* negation,
+ * forever. `.resolves` and `.rejects` are on a second prototype that only
+ * [`expectValue`]'s object has, so `expect(p).not.resolves` stays what it was —
+ * not a thing.
  */
-function bind(received: mixed, negated: boolean): $FlowFixMe {
-  const table = verdicts(received);
+type Bound = { readonly received: mixed, readonly negated: boolean, ... };
+
+/** The two prototypes, built on first use; see [`bind`]. */
+type Prototypes = {| readonly bound: interface {}, readonly root: interface {} |};
+let prototypes: Prototypes | null = null;
+
+/** A getter for matcher `name`, handing back a function bound to its object. */
+function matcherGetter(name: string): (this: Bound) => (...args: $ReadOnlyArray<mixed>) => mixed {
+  return function (this: Bound) {
+    const self = this;
+    return (...args: $ReadOnlyArray<mixed>) => apply(self, name, args);
+  };
+}
+
+function negation(this: Bound): mixed {
+  return bind(this.received, !this.negated);
+}
+
+function resolution(this: Bound): mixed {
+  return settled(this.received, "resolve", false);
+}
+
+function rejection(this: Bound): mixed {
+  return settled(this.received, "reject", false);
+}
+
+function matcherPrototypes(): Prototypes {
+  if (prototypes != null) {
+    return prototypes;
+  }
   const bound: $FlowFixMe = {};
-  for (const name of Object.keys(table)) {
-    const decide = (verdict: Verdict) => {
-      if (verdict.pass !== negated) {
-        return undefined;
-      }
-      const message = negated ? verdict.negatedFailure() : verdict.failure();
-      throw new AssertionError(
-        message,
-        name,
-        verdict.expected ?? "",
-        verdict.received ?? render(received),
-      );
-    };
-    bound[name] = (...args: $ReadOnlyArray<mixed>) => {
-      const verdict = table[name](...args);
-      // A matcher whose engine is asynchronous answers with a promise of a
-      // verdict, and the promise is handed straight back rather than hidden.
-      //
-      // Hiding it was the alternative and it cannot be done: the only way to
-      // present an asynchronous answer synchronously is to decide before it
-      // arrives, which is deciding without it. What the promise costs is a
-      // forgotten `await`, and that case is not silent either — the rejection
-      // reaches the worker's unhandled-rejection handler, which fails the file
-      // the promise was created in and prints this same message. A missing
-      // `await` on a passing audit is the one case nothing reports, and it is
-      // the case where nothing happened.
-      //
-      // `instanceof Promise` rather than a `then` test, and it is safe for a
-      // reason that would not survive being generalised: every entry in the
-      // table is written in this file, so the only promise that can arrive
-      // here is one an `async` function in this module made, in this realm. A
-      // matcher registered from outside — which `@uniflowed/test` has no API
-      // for, deliberately — could hand back a foreign thenable, and this line
-      // would be the thing to revisit.
-      return verdict instanceof Promise ? verdict.then(decide) : decide(verdict);
-    };
+  for (const name of Object.keys(verdicts(undefined))) {
+    Object.defineProperty(bound, name, { get: matcherGetter(name) });
   }
-  Object.defineProperty(bound, "not", { get: () => bind(received, !negated) });
+  Object.defineProperty(bound, "not", { get: negation });
+  const root: $FlowFixMe = Object.create(bound);
+  Object.defineProperty(root, "resolves", { get: resolution });
+  Object.defineProperty(root, "rejects", { get: rejection });
+  prototypes = { bound, root };
+  return prototypes;
+}
+
+/** Decide matcher `name` on `bound`'s value, raising when it does not hold. */
+function apply(bound: Bound, name: string, args: $ReadOnlyArray<mixed>): mixed {
+  const { received, negated } = bound;
+  const decide = (verdict: Verdict) => {
+    if (verdict.pass !== negated) {
+      return undefined;
+    }
+    const message = negated ? verdict.negatedFailure() : verdict.failure();
+    throw new AssertionError(
+      message,
+      name,
+      verdict.expected ?? "",
+      verdict.received ?? render(received),
+    );
+  };
+  const verdict = verdicts(received)[name](...args);
+  // A matcher whose engine is asynchronous answers with a promise of a
+  // verdict, and the promise is handed straight back rather than hidden.
+  //
+  // Hiding it was the alternative and it cannot be done: the only way to
+  // present an asynchronous answer synchronously is to decide before it
+  // arrives, which is deciding without it. What the promise costs is a
+  // forgotten `await`, and that case is not silent either — the rejection
+  // reaches the worker's unhandled-rejection handler, which fails the file
+  // the promise was created in and prints this same message. A missing
+  // `await` on a passing audit is the one case nothing reports, and it is
+  // the case where nothing happened.
+  //
+  // `instanceof Promise` rather than a `then` test, and it is safe for a
+  // reason that would not survive being generalised: every entry in the
+  // table is written in this file, so the only promise that can arrive
+  // here is one an `async` function in this module made, in this realm. A
+  // matcher registered from outside — which `@uniflowed/test` has no API
+  // for, deliberately — could hand back a foreign thenable, and this line
+  // would be the thing to revisit.
+  return verdict instanceof Promise ? verdict.then(decide) : decide(verdict);
+}
+
+function bind(received: mixed, negated: boolean): $FlowFixMe {
+  const bound: $FlowFixMe = Object.create(matcherPrototypes().bound);
+  bound.received = received;
+  bound.negated = negated;
   return bound;
 }
 
@@ -938,11 +994,9 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
  * received, for the reasons this module's header sets out.
  */
 function expectValue(received: mixed): Expectation {
-  const expectation: $FlowFixMe = bind(received, false);
-  Object.defineProperty(expectation, "resolves", {
-    get: () => settled(received, "resolve", false),
-  });
-  Object.defineProperty(expectation, "rejects", { get: () => settled(received, "reject", false) });
+  const expectation: $FlowFixMe = Object.create(matcherPrototypes().root);
+  expectation.received = received;
+  expectation.negated = false;
   return expectation;
 }
 

package/internal/frames.js

@@ -195,3 +195,181 @@ export function userFrames(stack: string | null | void): string | null {
   const frames = lines.slice(1).filter((frame) => !isInternalFrame(frame));
   return frames.length === 0 ? head : [head, ...frames].join("\n");
 }
+
+/**
+ * A V8 call site, as much of it as [`callerSite`] reads.
+ *
+ * Written out rather than imported: there is no library definition for V8's
+ * structured stack API, and these four methods are all it asks of one.
+ */
+type CallSite = interface {
+  getFileName(): ?string,
+  getLineNumber(): ?number,
+  getColumnNumber(): ?number,
+};
+
+/** The piece of `node:module`'s source-map API [`callerSite`] needs. */
+type SourceMapEntry = {|
+  readonly originalLine?: number,
+  readonly originalColumn?: number,
+  readonly originalSource?: string,
+|};
+type FindSourceMap = (
+  file: string,
+) => ?interface { findEntry(line: number, column: number): SourceMapEntry };
+
+/**
+ * `node:module`'s `findSourceMap` when the host is Node with source maps on;
+ * `false` when the structured path must not be taken; `undefined` until asked.
+ *
+ * Asked once per process: the host does not change under a running worker.
+ */
+let nodeSourceMaps: FindSourceMap | false | void;
+
+/**
+ * How to map a generated position the way Node's own stack traces do, or
+ * `false` when this host's stacks cannot be reproduced from call sites.
+ *
+ * Node only. Bun and Deno implement the call-site API too, but whether their
+ * call sites carry the generated position or the mapped one is theirs to
+ * decide and has changed between releases, so they keep the string path,
+ * whose answer is by construction the one their `.stack` prints. A browser
+ * has no `process` at all.
+ */
+function sourceMapsForCallSites(): FindSourceMap | false {
+  if (nodeSourceMaps !== undefined) {
+    return nodeSourceMaps;
+  }
+  const host: $FlowFixMe = globalThis;
+  const process = host.process;
+  const isNode =
+    typeof process?.versions?.node === "string" &&
+    process.versions.bun == null &&
+    host.Deno == null &&
+    typeof process.getBuiltinModule === "function" &&
+    typeof Error.captureStackTrace === "function";
+  if (!isNode) {
+    nodeSourceMaps = false;
+    return false;
+  }
+  const findSourceMap = process.getBuiltinModule("node:module")?.findSourceMap;
+  nodeSourceMaps =
+    typeof findSourceMap === "function"
+      ? // Only while Node applies source maps to its own stacks: with them off
+        // a `.stack` prints the generated position, and so must this.
+        (file) => (process.sourceMapsEnabled === true ? findSourceMap(file) : null)
+      : false;
+  return nodeSourceMaps;
+}
+
+/**
+ * The first position outside the runner on the stack of the call to `skip`,
+ * as `firstUserSite(new Error().stack)` would read it — or `undefined` when
+ * this host cannot answer that way, and the caller should build the string.
+ *
+ * # Why not simply read `.stack`
+ *
+ * Because it is the most expensive line in registering a test. `describe` and
+ * `it` ask where they were called from, once per case, and on Node with
+ * `--enable-source-maps` — which every `uf test` worker runs with — the string
+ * `.stack` is built by mapping *every* frame through its module's source map
+ * and printing each one, to read back one line and column from the first that
+ * is not the runner's. On a suite of 50 files and 1,000 cases that was about a
+ * sixth of a worker's CPU.
+ *
+ * V8 hands the same frames over unprinted to a `prepareStackTrace` installed
+ * for the one capture, and only the frame the answer comes from is mapped,
+ * with the lookup Node's printer itself uses — `findSourceMap(file)` then
+ * `findEntry(line - 1, column - 1)`, falling back to the generated position
+ * when there is no map or no entry — so the number is the one the string would
+ * have carried. `packages/test/registration-site.test.js` holds the two paths
+ * to that.
+ */
+export function callerSite(skip: (...args: $ReadOnlyArray<empty>) => mixed): Site | null | void {
+  const findSourceMap = sourceMapsForCallSites();
+  if (findSourceMap === false) {
+    return undefined;
+  }
+  const errors: $FlowFixMe = Error;
+  const limit: mixed = errors.stackTraceLimit;
+  const full = typeof limit === "number" ? limit : 0;
+  // A few frames first. The caller of a registration is two or three frames
+  // above it — `it`, the modifier or `each` wrapper, `addCase` — and V8's cost
+  // is per frame it materialises, so the whole default ten is walked only for
+  // the rare caller that is deeper than that.
+  const shallow = Math.min(full, SHALLOW_FRAMES);
+  const first = readCallSites(skip, shallow);
+  if (first === undefined) {
+    return undefined;
+  }
+  const found = firstUserCallSite(first, findSourceMap);
+  if (found != null || first.length < shallow || shallow === full) {
+    return found;
+  }
+  const again = readCallSites(skip, full);
+  return again === undefined ? undefined : firstUserCallSite(again, findSourceMap);
+}
+
+/** How many frames [`callerSite`] asks for before it asks for all of them. */
+const SHALLOW_FRAMES = 4;
+
+/** Hands V8's call sites back unprinted; one function, so none is made per capture. */
+function unprinted(_error: mixed, sites: $ReadOnlyArray<CallSite>): $ReadOnlyArray<CallSite> {
+  return sites;
+}
+
+/**
+ * Up to `limit` call sites above `skip`, or `undefined` when the host does not
+ * hand them over.
+ */
+function readCallSites(
+  skip: (...args: $ReadOnlyArray<empty>) => mixed,
+  limit: number,
+): $ReadOnlyArray<CallSite> | void {
+  const errors: $FlowFixMe = Error;
+  const prepare = errors.prepareStackTrace;
+  const before = errors.stackTraceLimit;
+  const holder: $FlowFixMe = {};
+  try {
+    errors.prepareStackTrace = unprinted;
+    errors.stackTraceLimit = limit;
+    errors.captureStackTrace(holder, skip);
+    // Read inside the `try`: V8 formats `stack` lazily, on first access, and
+    // with whatever `prepareStackTrace` is installed *then*. What comes back is
+    // what `unprinted` returned, which V8 does not type.
+    const sites: $FlowFixMe = holder.stack;
+    return Array.isArray(sites) ? sites : undefined;
+  } finally {
+    errors.prepareStackTrace = prepare;
+    errors.stackTraceLimit = before;
+  }
+}
+
+/** The first of `sites` outside the runner, mapped as Node maps a printed frame. */
+function firstUserCallSite(
+  sites: $ReadOnlyArray<CallSite>,
+  findSourceMap: FindSourceMap,
+): Site | null {
+  for (const site of sites) {
+    const file = site.getFileName();
+    if (file == null || isInternalFrame(file)) {
+      continue;
+    }
+    const line = site.getLineNumber();
+    const column = site.getColumnNumber();
+    if (line == null || column == null) {
+      continue;
+    }
+    const entry = findSourceMap(file)?.findEntry(line - 1, column - 1);
+    if (
+      entry?.originalSource != null &&
+      entry.originalSource !== "" &&
+      entry.originalLine != null &&
+      entry.originalColumn != null
+    ) {
+      return { line: entry.originalLine + 1, column: entry.originalColumn + 1 };
+    }
+    return { line, column };
+  }
+  return null;
+}

package/internal/registry.js

@@ -19,7 +19,7 @@
 // * `.only` anywhere in the file restricts the file to marked cases and their
 //   ancestors; everything else is reported skipped, never silently dropped.
 
-import { firstUserSite } from "./frames.js";
+import { callerSite, firstUserSite } from "./frames.js";
 
 /** The placeholders `it.each` substitutes a row into. */
 const ROW_TOKEN = /%[sjdi]/g;
@@ -27,6 +27,16 @@ const ROW_TOKEN = /%[sjdi]/g;
 /** What a test or hook body may return. */
 export type Body = () => mixed | Promise<mixed>;
 
+/**
+ * One `beforeAll`, `afterAll`, `beforeEach` or `afterEach`.
+ *
+ * `timeoutMs` is the hook's own budget when its registration named one, and
+ * `null` when the hook runs under the budget of the case it belongs to. A hook
+ * that starts a process or a server needs longer than the cases it sets up for,
+ * and without a budget of its own the only lever was the file-wide timeout.
+ */
+export type Hook = {| readonly body: Body, readonly timeoutMs: number | null |};
+
 /** The suffix written on a registration call. */
 export type Modifier = "none" | "only" | "skip" | "todo";
 
@@ -63,10 +73,10 @@ export type 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 beforeAll: Array<Hook>,
+  readonly afterAll: Array<Hook>,
+  readonly beforeEach: Array<Hook>,
+  readonly afterEach: Array<Hook>,
   readonly line: number,
   readonly column: number,
 |};
@@ -118,6 +128,10 @@ export function collected(): Suite {
  * treats as "unknown" rather than as line one.
  */
 function callSite(): {| readonly line: number, readonly column: number |} {
+  const site = callerSite(callSite);
+  if (site !== undefined) {
+    return site ?? { line: 0, column: 0 };
+  }
   return firstUserSite(new Error("position").stack) ?? { line: 0, column: 0 };
 }
 
@@ -276,22 +290,42 @@ function formatRow(name: string, row: mixed): string {
   });
 }
 
-/** Run once before the first test in this suite that runs. */
-export function beforeAll(body: Body): void {
-  current.beforeAll.push(body);
+/**
+ * A hook's own budget, from the second argument of its registration.
+ *
+ * `{ timeout }` is what `it` takes, and a bare number is what Jest and Vitest
+ * take — a suite moved from either writes `beforeAll(start, 30_000)`, and a
+ * budget that was silently dropped would fail as a timeout the file never
+ * asked for.
+ */
+function hookTimeout(options: ?(TestOptions | number)): number | null {
+  if (typeof options === "number") {
+    return options;
+  }
+  return options?.timeout ?? null;
+}
+
+/**
+ * Run once before the first test in this suite that runs.
+ *
+ * When it fails, every case it was setting up for fails with its error: none
+ * of them runs against a setup that did not happen.
+ */
+export function beforeAll(body: Body, options?: TestOptions | number): void {
+  current.beforeAll.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run once after the last test in this suite that ran. */
-export function afterAll(body: Body): void {
-  current.afterAll.push(body);
+export function afterAll(body: Body, options?: TestOptions | number): void {
+  current.afterAll.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run before every test in this suite and its children. */
-export function beforeEach(body: Body): void {
-  current.beforeEach.push(body);
+export function beforeEach(body: Body, options?: TestOptions | number): void {
+  current.beforeEach.push({ body, timeoutMs: hookTimeout(options) });
 }
 
 /** Run after every test in this suite and its children, including failures. */
-export function afterEach(body: Body): void {
-  current.afterEach.push(body);
+export function afterEach(body: Body, options?: TestOptions | number): void {
+  current.afterEach.push({ body, timeoutMs: hookTimeout(options) });
 }

package/internal/run.js

@@ -13,7 +13,14 @@ 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 BenchOptions, type Body, type Case, type Suite, collected } from "./registry.js";
+import {
+  type BenchOptions,
+  type Body,
+  type Case,
+  type Hook,
+  type Suite,
+  collected,
+} from "./registry.js";
 
 /** How one case ended. */
 export type Outcome =
@@ -186,8 +193,8 @@ function failure(thrown: mixed, file: string | null): Outcome {
 /** Everything one case needs from the suites above it. */
 type Context = {|
   readonly path: $ReadOnlyArray<string>,
-  readonly beforeEach: $ReadOnlyArray<Body>,
-  readonly afterEach: $ReadOnlyArray<Body>,
+  readonly beforeEach: $ReadOnlyArray<Hook>,
+  readonly afterEach: $ReadOnlyArray<Hook>,
   readonly skipped: boolean,
   readonly onlyPath: boolean,
 |};
@@ -268,7 +275,7 @@ async function runCase(
   await output.runInTest(name, async () => {
     try {
       for (const hook of context.beforeEach) {
-        await withTimeout(hook, timeoutMs);
+        await withTimeout(hook.body, hook.timeoutMs ?? timeoutMs);
       }
       if (benchmark) {
         samples = await measure(body, test.bench, timeoutMs);
@@ -282,7 +289,7 @@ async function runCase(
     // when the body had not already failed.
     for (const hook of context.afterEach) {
       try {
-        await withTimeout(hook, timeoutMs);
+        await withTimeout(hook.body, hook.timeoutMs ?? timeoutMs);
       } catch (thrown) {
         if (outcome.status === "passed") {
           outcome = failure(thrown, options.file ?? null);
@@ -396,16 +403,25 @@ async function runSuite(
   // 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.
+  //
+  // Once, and remembered either way. The outcome is kept rather than a "done"
+  // flag, because a flag raised before the hooks ran let every case after the
+  // first go ahead when setup had failed: the first case reported the hook's
+  // error and the rest ran against a fixture that was never made, failing — or
+  // worse, passing — for reasons that had nothing to do with them.
   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);
+  let setup: Promise<void> | null = null;
+  const setUpOnce = (): Promise<void> => {
+    if (setup == null) {
+      setUp = true;
+      setup = (async () => {
+        await setUpAncestors();
+        for (const hook of node.beforeAll) {
+          await withTimeout(hook.body, hook.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        }
+      })();
     }
+    return setup;
   };
 
   let passed = true;
@@ -455,7 +471,7 @@ async function runSuite(
   if (setUp) {
     for (const hook of node.afterAll) {
       try {
-        await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        await withTimeout(hook.body, hook.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
       } catch {
         // A teardown failure cannot fail a test that already reported, and
         // there is nothing left to attach it to; the file's own status carries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
@@ -38,7 +38,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.1.0",
+    "@uniflowed/host": "0.2.0",
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"
   },

package/worker.js

@@ -355,4 +355,21 @@ process.on("unhandledRejection", (reason: mixed) => {
   process.exit(1);
 });
 
+// The same for an exception nothing caught — a server's `error` event with no
+// listener, a throw from a timer callback. Node's default prints the stack to
+// stderr and exits, and all `uf` could then say was that the worker had died:
+// the file that did it went unnamed, and the message was somewhere above the
+// report, unattributed. Reported the way a rejection is, it is the failure of
+// the file whose work threw, with its message and stack in the file's result.
+process.on("uncaughtException", (thrown: mixed) => {
+  const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+  write({
+    event: "file",
+    status: "run-failed",
+    message: `uncaught exception: ${error.message}`,
+    stack: error.stack ?? null,
+  });
+  process.exit(1);
+});
+
 serve();