@ultimat3/testing 22.14.0 → 23.0.0

package/src/test-types.ts

@@ -4,6 +4,8 @@
 
 import { test } from 'bun:test';
 import { TestEvalThresholdError } from './errors';
+import type { FixtureBody } from './fixtures';
+import { runWithFixtures } from './fixtures';
 
 export const TEST_TYPES = ['unit', 'contract', 'live', 'job', 'e2e', 'eval'] as const;
 
@@ -13,27 +15,39 @@ export const SEPARATOR = ' · ';
 
 export const testName = (type: TestType, name: string): string => `${type}${SEPARATOR}${name}`;
 
-export type TestBody = () => void | Promise<void>;
+/**
+ * What a typed test may say about itself beyond its body. One key today: a deliberately heavy
+ * test (48 PDF renders) used to have to drop to `test(testName('unit', …), body, 30_000)` to
+ * outlive Bun's 5 s default, which is the one-way rule broken for a number (#589).
+ */
+export interface TestOptions {
+  /** This test's own deadline in milliseconds, handed to `bun:test`. Absent is Bun's default. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * One typed registrar. The body is `test`'s own (`FixtureBody`): it is handed the fixture bag and
+ * only what it destructures is built, so `unitTest('…', async ({ runJobs }) => …)` is a job body
+ * under the `unit` step with no `describe(testName('unit', …))` around a bare `test`. A body that
+ * destructures nothing builds nothing — the wrapper costs it one resolved promise.
+ */
+const typed =
+  (type: TestType) =>
+  (name: string, body: FixtureBody, options?: TestOptions): void => {
+    test(testName(type, name), () => runWithFixtures(body), options?.timeoutMs);
+  };
 
 /** Pure logic: no database, no clock, no network. The cheapest test that can fail for real. */
-export const unitTest = (name: string, body: TestBody): void => {
-  test(testName('unit', name), body);
-};
+export const unitTest = typed('unit');
 
 /** The published surface: OpenAPI diff against the committed spec, MCP exposure, error codes. */
-export const contractTest = (name: string, body: TestBody): void => {
-  test(testName('contract', name), body);
-};
+export const contractTest = typed('contract');
 
 /** Live queries: assert exactly what each subscriber receives, snapshot then incremental patch. */
-export const liveTest = (name: string, body: TestBody): void => {
-  test(testName('live', name), body);
-};
+export const liveTest = typed('live');
 
 /** Jobs: step sequence, retries, idempotency. Never wall-clock sleeps — advance the frozen clock. */
-export const jobTest = (name: string, body: TestBody): void => {
-  test(testName('job', name), body);
-};
+export const jobTest = typed('job');
 
 /** One element selection, resolved when it is used rather than when it is built. */
 export interface LocatorLike {
@@ -90,7 +104,10 @@ export interface E2eFixtures {
 
 export type E2eBody = (fixtures: E2eFixtures) => Promise<void>;
 
-let e2eDriver: ((name: string, body: E2eBody) => void) | undefined;
+/** What registers one e2e test with a browser behind it. `options` is the test's own (`timeoutMs`). */
+export type E2eDriver = (name: string, body: E2eBody, options?: TestOptions) => void;
+
+let e2eDriver: E2eDriver | undefined;
 
 /**
  * Register the browser-backed driver. Without one, `e2eTest` skips loudly — the skipped test's own
@@ -105,7 +122,7 @@ let e2eDriver: ((name: string, body: E2eBody) => void) | undefined;
  * `As of 2026-08` there are zero registered drivers, so every `e2eTest` in the tree is a skip; the
  * framework's own `e2e` suites use plain `bun:test`.
  */
-export function useE2eDriver(driver: (name: string, body: E2eBody) => void): void {
+export function useE2eDriver(driver: E2eDriver): void {
   e2eDriver = driver;
 }
 
@@ -123,7 +140,7 @@ export const resetE2eDriver = (): void => {
   e2eDriver = undefined;
 };
 
-export const e2eTest = (name: string, body: E2eBody): void => {
+export const e2eTest = (name: string, body: E2eBody, options?: TestOptions): void => {
   if (e2eDriver === undefined) {
     test.skip(
       testName('e2e', `${name} (no browser driver: x build --target static && x e2e)`),
@@ -131,7 +148,7 @@ export const e2eTest = (name: string, body: E2eBody): void => {
     );
     return;
   }
-  e2eDriver(testName('e2e', name), body);
+  e2eDriver(testName('e2e', name), body, options);
 };
 
 export interface EvalCase<TInput, TOutput> {
@@ -141,7 +158,7 @@ export interface EvalCase<TInput, TOutput> {
   score(output: TOutput): number | Promise<number>;
 }
 
-export interface EvalOptions<TInput, TOutput> {
+export interface EvalOptions<TInput, TOutput> extends TestOptions {
   readonly threshold: number;
   readonly cases: readonly EvalCase<TInput, TOutput>[];
   run(input: TInput): Promise<TOutput>;
@@ -155,18 +172,24 @@ export function evalTest<TInput, TOutput>(
   name: string,
   options: EvalOptions<TInput, TOutput>,
 ): void {
-  test(testName('eval', name), async () => {
-    const scores: { readonly name: string; readonly score: number }[] = [];
-    for (const testCase of options.cases) {
-      const output = await options.run(testCase.input);
-      scores.push({ name: testCase.name, score: await testCase.score(output) });
-    }
-    const failures = scores.filter((entry) => entry.score < options.threshold);
-    if (failures.length > 0) {
-      const detail = failures.map((entry) => `${entry.name}=${entry.score.toFixed(2)}`).join(', ');
-      throw new TestEvalThresholdError({ name, threshold: options.threshold, detail });
-    }
-  });
+  test(
+    testName('eval', name),
+    async () => {
+      const scores: { readonly name: string; readonly score: number }[] = [];
+      for (const testCase of options.cases) {
+        const output = await options.run(testCase.input);
+        scores.push({ name: testCase.name, score: await testCase.score(output) });
+      }
+      const failures = scores.filter((entry) => entry.score < options.threshold);
+      if (failures.length > 0) {
+        const detail = failures
+          .map((entry) => `${entry.name}=${entry.score.toFixed(2)}`)
+          .join(', ');
+        throw new TestEvalThresholdError({ name, threshold: options.threshold, detail });
+      }
+    },
+    options.timeoutMs,
+  );
 }
 
 export interface OpenApiOperationLike {

package/src/e2e-dom-fixture.ts

@@ -1,122 +0,0 @@
-// A document small enough to hold in a test and real enough to RUN the driver's own in-page
-// expressions. Without it every claim about `getByRole` and `getByText` would be an assertion
-// about a string, and a string that never executes cannot be wrong about a page.
-//
-// Its own file, the pattern `dev-roles-fixture.ts` and `policy-fixture.ts` already set here.
-
-/** One element. `attrs` is data, so every read of it goes through `Object.hasOwn` below. */
-export interface FakeE2eElement {
-  readonly tag: string;
-  readonly attrs: Readonly<Record<string, string>>;
-  readonly text?: string;
-  readonly children?: readonly FakeE2eElement[];
-  /** What `getComputedStyle` answers. Absent is the browser's own default — visible. */
-  readonly style?: { display?: string; visibility?: string; opacity?: string };
-}
-
-interface Node {
-  tagName: string;
-  textContent: string;
-  readonly attributes: Record<string, string>;
-  readonly descendants: Node[];
-  readonly style: { display: string; visibility: string; opacity: string };
-  getAttribute(name: string): string | null;
-  setAttribute(name: string, value: string): void;
-  removeAttribute(name: string): void;
-  contains(other: Node): boolean;
-}
-
-const textOf = (element: FakeE2eElement): string =>
-  [element.text ?? '', ...(element.children ?? []).map(textOf)]
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-function build(element: FakeE2eElement): Node {
-  const attributes: Record<string, string> = { ...element.attrs };
-  const children = (element.children ?? []).map(build);
-  const descendants = children.flatMap((child) => [child, ...child.descendants]);
-  const node: Node = {
-    tagName: element.tag.toUpperCase(),
-    textContent: textOf(element),
-    attributes,
-    descendants,
-    style: {
-      display: element.style?.display ?? 'block',
-      visibility: element.style?.visibility ?? 'visible',
-      opacity: element.style?.opacity ?? '1',
-    },
-    getAttribute: (name) => (Object.hasOwn(attributes, name) ? (attributes[name] as string) : null),
-    setAttribute: (name, value) => {
-      attributes[name] = value;
-    },
-    removeAttribute: (name) => {
-      delete attributes[name];
-    },
-    contains: (other) => descendants.includes(other),
-  };
-  return node;
-}
-
-/**
- * `tag`, `*`, `[attr]`, `[attr="value"]`, a trailing `:not([attr])` and any combination — every
- * shape this driver emits (`input:not([type])` is the textbox role's untyped input).
- */
-const SIMPLE = /^([a-zA-Z0-9*]*)((?:\[[^\]]*\])*)(?::not\(\[([^\]=]+)\]\))?$/;
-
-function matchesSimple(node: Node, selector: string): boolean {
-  const parsed = SIMPLE.exec(selector.trim());
-  if (parsed === null) return false;
-  const tag = parsed[1] ?? '';
-  if (tag !== '' && tag !== '*' && tag.toUpperCase() !== node.tagName) return false;
-  const absent = parsed[3]?.trim();
-  if (absent !== undefined && node.getAttribute(absent) !== null) return false;
-  for (const clause of (parsed[2] ?? '').matchAll(/\[([^\]=]+)(?:=("[^"]*"|[^\]]*))?\]/g)) {
-    const name = (clause[1] ?? '').trim();
-    const held = node.getAttribute(name);
-    if (held === null) return false;
-    const raw = clause[2];
-    if (raw !== undefined && held !== raw.replace(/^"|"$/g, '')) return false;
-  }
-  return true;
-}
-
-const matches = (node: Node, selector: string): boolean =>
-  selector.split(',').some((part) => part.trim() !== '' && matchesSimple(node, part));
-
-/**
- * The globals a driver expression names, bound to one tree. `getComputedStyle` and `document` are
- * handed in as arguments rather than assigned to `globalThis`: a test that installed a fake
- * `document` on the process would leak it into every later file in the run.
- */
-export function fakeE2eDocument(root: FakeE2eElement): Readonly<Record<string, unknown>> {
-  const rootNode = build(root);
-  const all = [rootNode, ...rootNode.descendants];
-  return {
-    document: {
-      querySelectorAll: (selector: string): Node[] => all.filter((node) => matches(node, selector)),
-      querySelector: (selector: string): Node | null =>
-        all.find((node) => matches(node, selector)) ?? null,
-      getElementById: (id: string): Node | null =>
-        all.find((node) => node.getAttribute('id') === id) ?? null,
-    },
-    getComputedStyle: (node: Node) => node.style,
-  };
-}
-
-/**
- * Run an expression the driver built, in THIS process, against a stubbed global scope.
- *
- * `new Function` and not `eval`: the body evaluates with no access to this module's scope, so a
- * name the expression does not receive as a parameter is genuinely free — which is exactly the
- * `ReferenceError` a captured closure produces in a real browser, and the thing the evaluate
- * wrapper has to be proved against.
- */
-export async function runInFakePage(
-  expression: string,
-  globals: Readonly<Record<string, unknown>> = {},
-): Promise<unknown> {
-  const names = Object.keys(globals);
-  const body = new Function(...names, `return (${expression});`) as (...args: unknown[]) => unknown;
-  return await body(...names.map((name) => globals[name]));
-}