@ultimat3/testing 27.11.0 → 27.13.0

package/README.md

@@ -205,8 +205,13 @@ there is no flag on the fixture and no code to silence.
 
 Each takes an optional `{ timeoutMs }` after the body — `unitTest(name, body, { timeoutMs: 30_000 })`,
 and `test` takes the same; `evalTest` reads it off its options — handed to `bun:test` as that
-test's own deadline (`TestOptions`). Absent is Bun's 5 s default. An `E2eDriver` receives it as its
-third argument. `unitTest`, `contractTest`, `liveTest` and `jobTest` hand their body the
+test's own deadline (`TestOptions`), at this machine's pace. Absent is Bun's 5 s default, which
+`x verify` paces the same way. An `E2eDriver` receives it as its third argument.
+
+**`paced(ms)`** is a declared deadline at this machine's pace, for a bare `test(…, paced(90_000))`:
+`ms` times `ULTIMATE_TEST_PACE`, which `x verify` measures and sets on every test run it starts —
+1 on a 4-core CI runner, more on a 2-core or slower box. Absent (a hand-run `bun test`) is 1; a
+value that is not a number at or above 1 is `X_TEST_PACE_INVALID`. `unitTest`, `contractTest`, `liveTest` and `jobTest` hand their body the
 [fixture bag](#fixtures); `e2eTest` hands its own (`E2eFixtures`).
 
 **Registering one, `As of 2026-08-25`.** `@ultimat3/cli`'s `installE2eDriver({ page, baseUrl })` is
@@ -305,9 +310,15 @@ its own, so one shared store is enough.
 ## Parallel databases
 
 ```ts
-const db = await acquireWorkerDatabase({ adminUrl, migrate });
+import { acquireWorkerDatabase } from '@ultimat3/testing';
+
+// `migrate: (url) => …` applies the app's schema into the template once; omitted here.
+await using db = await acquireWorkerDatabase({ adminUrl: Bun.env['TEST_DATABASE_URL'] });
 ```
 
+The handle is async-disposable (`As of 2026-10-18`): `await using` drops the worker's database when
+the scope ends, a failed test included; `db.drop()` is the same call spelled by hand.
+
 The first worker creates the template under a Postgres advisory lock and migrates it; every
 worker then clones it copy-on-write, under the same lock — a clone waits only 5 s for a session on
 the template to leave, and the next worker's migration holds one. With no Postgres configured it falls back to PGlite, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "27.11.0",
+  "version": "27.13.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -36,20 +36,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.11.0",
-    "@ultimat3/cache": "27.11.0",
-    "@ultimat3/core": "27.11.0",
-    "@ultimat3/db": "27.11.0",
-    "@ultimat3/entity": "27.11.0",
-    "@ultimat3/http": "27.11.0",
-    "@ultimat3/i18n": "27.11.0",
-    "@ultimat3/jobs": "27.11.0",
-    "@ultimat3/mail": "27.11.0",
-    "@ultimat3/policy": "27.11.0",
-    "@ultimat3/pwa": "27.11.0",
-    "@ultimat3/query": "27.11.0",
-    "@ultimat3/realtime": "27.11.0",
-    "@ultimat3/render": "27.11.0",
-    "@ultimat3/time": "27.11.0"
+    "@ultimat3/action": "27.13.0",
+    "@ultimat3/cache": "27.13.0",
+    "@ultimat3/core": "27.13.0",
+    "@ultimat3/db": "27.13.0",
+    "@ultimat3/entity": "27.13.0",
+    "@ultimat3/http": "27.13.0",
+    "@ultimat3/i18n": "27.13.0",
+    "@ultimat3/jobs": "27.13.0",
+    "@ultimat3/mail": "27.13.0",
+    "@ultimat3/policy": "27.13.0",
+    "@ultimat3/pwa": "27.13.0",
+    "@ultimat3/query": "27.13.0",
+    "@ultimat3/realtime": "27.13.0",
+    "@ultimat3/render": "27.13.0",
+    "@ultimat3/time": "27.13.0"
   }
 }

package/src/cdp-e2e-session.ts

@@ -7,6 +7,7 @@ import type { CdpConnection } from './cdp-connection';
 import type { E2eTab } from './cdp-e2e-page';
 import { cdpE2eTab } from './cdp-e2e-page';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { isNetworkProbe, networkAgrees } from './cdp-network-probe';
 import { offlineScripts } from './cdp-offline-script';
 
 export interface E2eSession {
@@ -92,6 +93,8 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
   });
   connection.on('Network.requestWillBeSent', (params) => {
     const request = params['request'];
+    // The switch's own proof, not the app's traffic: a test that counts requests never sees it.
+    if (isNetworkProbe(field(request, 'url') ?? '')) return;
     requests.push(`${field(request, 'method') ?? '?'} ${field(request, 'url') ?? ''}`);
   });
   connection.on('Target.attachedToTarget', (params) => {
@@ -232,13 +235,20 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
   const confirmed = async (online: boolean): Promise<void> => {
     const deadline = performance.now() + options.loadTimeoutMs;
     const open = [...pageSessions].filter((session) => sessions.has(session));
+    // `navigator.onLine` first, then a real request: Chrome tells the page before its network
+    // service applies the cut, so the first alone let a `fetch` through (`cdp-network-probe.ts`).
     const answers = await Promise.all(
-      open.map(async (session) => [session, await pageReads(session, online, deadline)] as const),
+      open.map(async (session) => {
+        const reads =
+          (await pageReads(session, online, deadline)) &&
+          (await networkAgrees(send, session, online, deadline));
+        return [session, reads] as const;
+      }),
     );
     const waiting = answers.filter(([, reads]) => !reads).map(([session]) => session);
     if (waiting.length > 0) {
       throw new CdpTimeoutError({
-        method: `${ON_LINE} === ${String(online)} in page session ${waiting.join(', ')}`,
+        method: `${ON_LINE} === ${String(online)} and a request ${online ? 'reaching' : 'refused'} in page session ${waiting.join(', ')}`,
         timeoutMs: options.loadTimeoutMs,
       });
     }

package/src/cdp-network-probe.ts

@@ -0,0 +1,80 @@
+// One responsibility: proving a page's NETWORK agrees with the offline switch, by sending a request.
+// `navigator.onLine` is not that proof: Chrome tells the renderer before the network service applies
+// the condition (two pipes, no order between them), so a `fetch` on the next line went through under
+// a cut the page already read as offline — `browser-harness.e2e.test.ts`, CI run 39223207154.
+
+import type { CdpResult } from './cdp-connection';
+
+type Send = (
+  method: string,
+  params: Record<string, unknown>,
+  session: string,
+  deadlineMs?: number,
+) => Promise<CdpResult>;
+
+/** The probe's path: under `/_x/`, which no app route owns, so the app answers it 404 and does nothing. */
+export const NETWORK_PROBE_PATH = '/_x/network-probe';
+
+/**
+ * `HEAD`, because the framework's service worker answers GET only — a GET could be served from its
+ * cache or its offline document, and read as `reached` under a cut forever. `none` on a page that is
+ * not on http(s) (`about:blank`): it has no origin to ask, and nothing on it can fetch either.
+ */
+export const NETWORK_PROBE = `(async () => {
+  if (location.protocol !== 'http:' && location.protocol !== 'https:') return 'none';
+  try {
+    await fetch('${NETWORK_PROBE_PATH}', { method: 'HEAD', cache: 'no-store' });
+    return 'reached';
+  } catch {
+    return 'refused';
+  }
+})()`;
+
+/** Whether a logged request URL is a probe — kept out of the session's request log. */
+export const isNetworkProbe = (url: string): boolean => {
+  try {
+    return new URL(url).pathname === NETWORK_PROBE_PATH;
+  } catch {
+    return false;
+  }
+};
+
+const probeValue = (answer: CdpResult): unknown => {
+  const result = answer.result?.['result'];
+  return typeof result === 'object' && result !== null
+    ? (result as Record<string, unknown>)['value']
+    : undefined;
+};
+
+/**
+ * Probes one page until a request from it is refused (`online` false) or reaches the server
+ * (`online` true), and answers `false` at `deadline`. Each probe is itself a round trip to the
+ * network, so the loop paces itself — no sleep. A probe refused by a navigation is asked again.
+ */
+export async function networkAgrees(
+  send: Send,
+  session: string,
+  online: boolean,
+  deadline: number,
+): Promise<boolean> {
+  const wanted = online ? 'reached' : 'refused';
+  for (;;) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) return false;
+    try {
+      const answer = await send(
+        'Runtime.evaluate',
+        { expression: NETWORK_PROBE, returnByValue: true, awaitPromise: true },
+        session,
+        remaining,
+      );
+      const value = probeValue(answer);
+      if (value === wanted || value === 'none') return true;
+    } catch {
+      // A navigation destroyed the context, or the call ran out of time: the deadline decides.
+    }
+    // One macrotask between probes: a refusal that settles as a microtask would otherwise starve
+    // every timer and socket in the process until the deadline.
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+}

package/src/e2e-driver.ts

@@ -9,6 +9,7 @@ import { FixtureUnavailableError } from './errors';
 import { withFailureContext } from './failure-context';
 import { unavailableFixture } from './fixture-drivers';
 import { defineFixtures } from './fixtures';
+import { paced } from './test-pace';
 import type { E2eBody, E2eFixtures, PageLike } from './test-types';
 import { resetE2eDriver, useE2eDriver } from './test-types';
 
@@ -107,7 +108,7 @@ export function installE2eDriver(options: E2eDriverOptions): () => void {
         throw withFailureContext(error);
       }
     };
-    bunTest(name, run, test?.timeoutMs);
+    bunTest(name, run, test?.timeoutMs === undefined ? undefined : paced(test.timeoutMs));
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-page.ts

@@ -62,6 +62,21 @@ const readField = (raw: unknown, key: string): unknown => {
 
 const TITLE = '(() => JSON.stringify({ title: document.title }))()';
 
+/**
+ * Where the server's SECOND flush begins: every hole a streamed page reveals is written as one
+ * chunk opening with this tag (`revealChunk` in `@ultimat3/render`'s `render-stream.ts`, which the
+ * barrel does not export). Everything before it is the first flush — the head and the shell.
+ */
+export const REVEAL_MARK = '<template data-x-hole=';
+
+/**
+ * How long the reader waits for the rest of a flush that arrived in pieces. One server flush is
+ * ONE `enqueue`, but the transport may hand it to the page as several chunks — a read of the first
+ * network chunk alone cut the shell mid-tag and failed `toContain` on a header it really sent.
+ * A pause this long ends the read when no hole has been revealed; a reveal ends it at once.
+ */
+export const FLUSH_IDLE_MS = 250;
+
 /**
  * The first flush, read by a `fetch` INSIDE the page after the navigation, because neither
  * `ScrapePage` nor `CdpPageLike` exposes a response body — puppeteer's `page.on('response')` is
@@ -70,15 +85,37 @@ const TITLE = '(() => JSON.stringify({ title: document.title }))()';
  * The cost, stated rather than hidden: this is a SECOND request to the same route, so what it
  * measures is that route's streaming behaviour and not the byte-for-byte first chunk the open
  * document received. It runs in the page, so it carries the page's cookies and its origin — a
- * `fetch` from the test process would carry neither. The reader is CANCELLED after that chunk: a
- * streamed response nobody pulls stays open until its last hole fills, holding one of the page's
- * six connections to its origin for the rest of the test.
+ * `fetch` from the test process would carry neither. Chunks are joined until the first reveal
+ * (cut there) or a pause of `FLUSH_IDLE_MS`, and the reader is then CANCELLED: a streamed response
+ * nobody pulls stays open until its last hole fills, holding one of the page's six connections to
+ * its origin for the rest of the test.
  */
 const firstFlushExpression = (url: string): string =>
   `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
-    .then((response) => { const reader = response.body.getReader(); return reader.read()
-      .then((chunk) => { reader.cancel().catch(() => {}); return chunk; }); })
-    .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
+    .then((response) => {
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      const mark = ${JSON.stringify(REVEAL_MARK)};
+      let html = '';
+      const finish = () => {
+        reader.cancel().catch(() => {});
+        const cut = html.indexOf(mark);
+        return JSON.stringify({ html: cut === -1 ? html : html.slice(0, cut) });
+      };
+      const pull = (first) => {
+        const read = reader.read();
+        const next = first ? read : Promise.race([
+          read,
+          new Promise((resolve) => setTimeout(() => resolve(null), ${FLUSH_IDLE_MS})),
+        ]);
+        return next.then((chunk) => {
+          if (chunk === null || chunk.done) return finish();
+          html += decoder.decode(chunk.value, { stream: true });
+          return html.includes(mark) ? finish() : pull(false);
+        });
+      };
+      return pull(true);
+    }))()`;
 
 /**
  * The adapter. Every member re-reads the live page: a `PageLike` handed to a test outlives every

package/src/errors.ts

@@ -48,6 +48,7 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_NUMBER_EXPECTED',
   'X_TEST_ISLAND_STATE_UNKNOWN',
   'X_TEST_APP_NOT_BOOTED',
+  'X_TEST_PACE_INVALID',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -88,6 +89,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_TEST_NUMBER_EXPECTED: 'a matcher expected a finite number and got something else',
   X_TEST_ISLAND_STATE_UNKNOWN: 'an island state manifest declares no state with that id',
   X_TEST_APP_NOT_BOOTED: 'describeApp handle read before boot',
+  X_TEST_PACE_INVALID: 'ULTIMATE_TEST_PACE is not a number at or above 1',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/fixtures.ts

@@ -18,6 +18,7 @@ import type { TestMail } from './fixture-mail';
 import type { TestNetwork } from './fixture-network';
 import type { TestPush } from './fixture-push';
 import type { TestStatements } from './fixture-statements';
+import { paced } from './test-pace';
 import type { PageLike, TestOptions } from './test-types';
 
 /** Built once per test, on first use. */
@@ -257,8 +258,13 @@ export async function runWithFixtures(body: FixtureRunBody): Promise<void> {
  * must not be the reason the next file inherits a queue.
  *
  * `options.timeoutMs` is the test's own deadline, the same key the six typed helpers take: a
- * fixture that builds something slow (an island, a browser) is the test that needs one.
+ * fixture that builds something slow (an island, a browser) is the test that needs one. Read at
+ * this machine's pace (`paced`), as the typed helpers read theirs.
  */
 export function fixtureTest(name: string, body: FixtureBody, options?: TestOptions): void {
-  bunTest(name, () => runWithFixtures(body), options?.timeoutMs);
+  bunTest(
+    name,
+    () => runWithFixtures(body),
+    options?.timeoutMs === undefined ? undefined : paced(options.timeoutMs),
+  );
 }

package/src/index.ts

@@ -340,7 +340,12 @@ export {
 } from './sealed-network';
 export type { SharedExamples } from './shared-examples';
 export { behavesLike, sharedExamples } from './shared-examples';
-export type { SqlRunner, TemplateDbConfig, WorkerDatabase } from './template-db';
+export type {
+  DisposableWorkerDatabase,
+  SqlRunner,
+  TemplateDbConfig,
+  WorkerDatabase,
+} from './template-db';
 export {
   acquireWorkerDatabase,
   cloneSql,
@@ -353,6 +358,7 @@ export {
   urlFor,
   workerId,
 } from './template-db';
+export { paced, TEST_PACE_ENV, TestPaceInvalidError, testPace } from './test-pace';
 export type {
   E2eBody,
   E2eDriver,

package/src/template-db.ts

@@ -30,6 +30,13 @@ export interface WorkerDatabase {
   drop(): Promise<void>;
 }
 
+/**
+ * What `acquireWorkerDatabase` answers: the handle plus `drop()` as its async disposer, so
+ * `await using db = await acquireWorkerDatabase()` releases it however the scope exits. A separate
+ * type so a hand-built `WorkerDatabase` (a fake `acquire`) owes no disposer.
+ */
+export type DisposableWorkerDatabase = WorkerDatabase & AsyncDisposable;
+
 export const DEFAULT_TEMPLATE = 'ultimate_test_template';
 
 /**
@@ -109,7 +116,7 @@ const defaultConnect = (url: string): SqlRunner => {
 export async function acquireWorkerDatabase(
   config: TemplateDbConfig = {},
   deps: Partial<TemplateDbDeps> = {},
-): Promise<WorkerDatabase> {
+): Promise<DisposableWorkerDatabase> {
   const env = deps.env ?? (Bun.env as Readonly<Record<string, string | undefined>>);
   const connect = deps.connect ?? defaultConnect;
   const template = config.templateName ?? DEFAULT_TEMPLATE;
@@ -118,13 +125,13 @@ export async function acquireWorkerDatabase(
   const adminUrl = config.adminUrl ?? env['TEST_DATABASE_URL'] ?? env['DATABASE_URL'];
 
   if (adminUrl === undefined || adminUrl.length === 0) {
-    return {
+    return disposable({
       kind: 'pglite',
       worker,
       database,
       url: `pglite://memory/${database}`,
       drop: async () => undefined,
-    };
+    });
   }
 
   const admin = connect(adminUrl);
@@ -160,7 +167,7 @@ export async function acquireWorkerDatabase(
   }
   await admin.close();
 
-  return {
+  return disposable({
     kind: 'postgres',
     worker,
     database,
@@ -170,7 +177,12 @@ export async function acquireWorkerDatabase(
       await cleanup.exec(dropSql(database));
       await cleanup.close();
     },
-  };
+  });
+}
+
+/** The handle with its `drop` as the async disposer, so `await using` is the one release spelling. */
+function disposable(db: WorkerDatabase): DisposableWorkerDatabase {
+  return { ...db, [Symbol.asyncDispose]: () => db.drop() };
 }
 
 /**

package/src/test-pace.ts

@@ -0,0 +1,36 @@
+// How much slower this machine runs than the one a test's declared deadline was measured on.
+// `x verify` measures it (`packages/cli/src/verify-pace.ts`) and hands it to every test run it
+// starts as `ULTIMATE_TEST_PACE`; a test's own timeout is read at that pace, so a 2-core 1.8 GHz
+// box is held to the same bound a CI runner is instead of failing on a number set for the runner.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** Set by `x verify` on each test run it starts. Absent — a hand-run `bun test` — is pace 1. */
+export const TEST_PACE_ENV = 'ULTIMATE_TEST_PACE';
+
+/** A pace that does not parse, or one below 1: a machine is never read as faster than the bound. */
+export class TestPaceInvalidError extends UltimateError {
+  constructor(value: string) {
+    super({
+      code: 'X_TEST_PACE_INVALID',
+      cause: `${TEST_PACE_ENV}=${JSON.stringify(value)} is not a number at or above 1`,
+      fix: `env -u ${TEST_PACE_ENV} bun test <file>   # the gate measures the pace and sets it on each test run itself; unset is pace 1`,
+    });
+  }
+}
+
+/** The pace this process was started at. */
+export function testPace(env: Readonly<Record<string, string | undefined>> = Bun.env): number {
+  const raw = env[TEST_PACE_ENV];
+  if (raw === undefined || raw.trim() === '') return 1;
+  const pace = Number(raw);
+  if (!Number.isFinite(pace) || pace < 1) throw new TestPaceInvalidError(raw);
+  return pace;
+}
+
+/**
+ * A declared test deadline at this machine's pace: `test(name, body, paced(90_000))`. The number
+ * stays the one measured on a fast machine; only a slower one stretches it.
+ */
+export const paced = (ms: number, env?: Readonly<Record<string, string | undefined>>): number =>
+  Math.round(ms * testPace(env));

package/src/test-types.ts

@@ -6,6 +6,7 @@ import { test } from 'bun:test';
 import { TestEvalThresholdError } from './errors';
 import type { FixtureBody } from './fixtures';
 import { runWithFixtures } from './fixtures';
+import { paced } from './test-pace';
 
 export const TEST_TYPES = ['unit', 'contract', 'live', 'job', 'e2e', 'eval'] as const;
 
@@ -21,7 +22,10 @@ export const testName = (type: TestType, name: string): string => `${type}${SEPA
  * 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. */
+  /**
+   * This test's own deadline in milliseconds, handed to `bun:test` at this machine's pace
+   * (`paced`). Absent is the run's default, which `x verify` paces the same way.
+   */
   readonly timeoutMs?: number;
 }
 
@@ -34,7 +38,11 @@ export interface TestOptions {
 const typed =
   (type: TestType) =>
   (name: string, body: FixtureBody, options?: TestOptions): void => {
-    test(testName(type, name), () => runWithFixtures(body), options?.timeoutMs);
+    test(
+      testName(type, name),
+      () => runWithFixtures(body),
+      options?.timeoutMs === undefined ? undefined : paced(options.timeoutMs),
+    );
   };
 
 /** Pure logic: no database, no clock, no network. The cheapest test that can fail for real. */
@@ -192,7 +200,7 @@ export function evalTest<TInput, TOutput>(
         throw new TestEvalThresholdError({ name, threshold: options.threshold, detail });
       }
     },
-    options.timeoutMs,
+    options.timeoutMs === undefined ? undefined : paced(options.timeoutMs),
   );
 }