@ultimat3/testing 21.0.0 → 22.0.0

package/src/e2e-page.ts

@@ -0,0 +1,153 @@
+// `PageLike` over a browser page. The adapter itself: `@ultimat3/testing` declares the surface an
+// e2e test drives and `@ultimat3/scraping` owns the only driver that can drive one, and neither
+// may import the other — so the join is here, in the one package allowed to know about both.
+
+import { finiteCount } from '@ultimat3/core';
+import { E2eServiceWorkerAbsentError } from './e2e-errors';
+import { evaluateClosure } from './e2e-evaluate';
+import { e2eLocator } from './e2e-locator';
+import type { E2eSelection } from './e2e-selection';
+import type { LocatorLike, PageLike } from './test-types';
+
+/**
+ * What this adapter needs of a browser: four required members, every one of them on `ScrapePage`.
+ * Declared structurally rather than as `ScrapePage` so a test can stand one up in six lines — the
+ * same bargain `cdp-port.ts` makes about puppeteer, one layer up.
+ */
+export interface E2eBrowserPage {
+  url(): string;
+  goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<unknown>;
+  evaluate(expression: string): Promise<unknown>;
+  click(selector: string): Promise<void>;
+  /**
+   * The browser's own network condition, which `E2eFixtures.offline()`/`online()` forward to.
+   * `ScrapePage` has it (`page-over-target.ts`), reaching `CdpPageLike.setOfflineMode` through
+   * `cdp-target.ts`'s guard.
+   *
+   * OPTIONAL for the reason the four above are structural: this port is the shape of somebody
+   * ELSE's object, and requiring it would cost every six-line double a type error for a capability
+   * a test that never goes offline does not need. Absent, `e2e-driver.ts` keeps refusing by name —
+   * a coded refusal, never a silent no-op, because an `offline()` that did nothing would let the
+   * app's ONLINE page pass an offline test.
+   */
+  offline?(enabled: boolean): Promise<void>;
+}
+
+export interface E2ePageOptions {
+  readonly page: E2eBrowserPage;
+  /** Every `goto('/feed')` in an e2e suite is app-relative; this is what makes one absolute. */
+  readonly baseUrl: string;
+  /** Per-navigation deadline, handed to the driver rather than enforced here. */
+  readonly timeoutMs?: number | undefined;
+  /** How long `waitForServiceWorker()` waits before refusing. Bounded IN THE PAGE. */
+  readonly serviceWorkerTimeoutMs?: number | undefined;
+}
+
+/** Named once, so both refusals below name the call an app's test preload actually makes. */
+const SUBJECT = 'installE2eDriver';
+
+export const DEFAULT_E2E_TIMEOUT_MS = 30_000;
+export const DEFAULT_SERVICE_WORKER_TIMEOUT_MS = 10_000;
+
+/** Every in-page expression here answers JSON text, for the reason `cdp-snapshot.ts` states. */
+const readField = (raw: unknown, key: string): unknown => {
+  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
+  return typeof decoded === 'object' && decoded !== null
+    ? (decoded as Record<string, unknown>)[key]
+    : undefined;
+};
+
+const TITLE = '(() => JSON.stringify({ title: document.title }))()';
+
+/**
+ * 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
+ * not on the port and adding it would be an edit to `@ultimat3/scraping`.
+ *
+ * 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.
+ */
+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()) })))()`;
+
+/**
+ * `ready` alone is not control: a first load activates a worker that is not yet the page's
+ * controller, and an offline assertion made in that window tests nothing. So this waits for
+ * `controllerchange` too — an EVENT, not a poll, so the harness still has exactly one retry loop.
+ */
+const serviceWorkerExpression = (timeoutMs: number): string =>
+  `(() => {
+  if (!navigator.serviceWorker) return JSON.stringify({ controlled: false });
+  const controlled = new Promise((resolve) => {
+    if (navigator.serviceWorker.controller) { resolve(true); return; }
+    navigator.serviceWorker.addEventListener('controllerchange', () => resolve(true), { once: true });
+  });
+  const deadline = new Promise((resolve) => setTimeout(() => resolve(false), ${String(timeoutMs)}));
+  return Promise.race([navigator.serviceWorker.ready.then(() => controlled), deadline])
+    .catch(() => false)
+    .then((ok) => JSON.stringify({ controlled: ok === true }));
+})()`;
+
+/**
+ * The adapter. Every member re-reads the live page: a `PageLike` handed to a test outlives every
+ * navigation the test makes, so nothing here may capture a URL, a document or an element.
+ */
+export function e2ePage(options: E2ePageOptions): PageLike {
+  const page = options.page;
+  // Both are screened HERE, at construction, and not where they land: `timeout` is handed to a
+  // driver that reads it as a deadline, and `swTimeout` is INTERPOLATED into the in-page source,
+  // where `setTimeout(fn, NaN)` is `setTimeout(fn, 0)` — so a NaN budget makes every
+  // `waitForServiceWorker()` refuse a worker that really did take control. A misdiagnosis reported
+  // as a test failure is worse than the failure. Floor 0, because a driver reads `timeout: 0` as
+  // "no deadline" and that is a value an app is entitled to declare.
+  const timeout = finiteCount(SUBJECT, 'timeoutMs', options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS);
+  const swTimeout = finiteCount(
+    SUBJECT,
+    'serviceWorkerTimeoutMs',
+    options.serviceWorkerTimeoutMs ?? DEFAULT_SERVICE_WORKER_TIMEOUT_MS,
+  );
+  const absolute = (url: string): string => new URL(url, options.baseUrl).toString();
+  const locate = (selection: E2eSelection): LocatorLike => e2eLocator(page, selection);
+
+  return {
+    url: () => page.url(),
+    goto: (url) => page.goto(absolute(url), { timeout }),
+    // The page's OWN url, re-read at call time: a reload of the url the adapter was built with
+    // would navigate away from wherever the test had got to.
+    reload: () => page.goto(page.url(), { timeout }),
+    title: async () => {
+      const title = readField(await page.evaluate(TITLE), 'title');
+      return typeof title === 'string' ? title : '';
+    },
+    gotoStreamed: async (url) => {
+      const target = absolute(url);
+      await page.goto(target, { timeout });
+      const html = readField(await page.evaluate(firstFlushExpression(target)), 'html');
+      return { html: typeof html === 'string' ? html : '' };
+    },
+    waitForServiceWorker: async () => {
+      const raw = await page.evaluate(serviceWorkerExpression(swTimeout));
+      if (readField(raw, 'controlled') !== true) {
+        throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs: swTimeout });
+      }
+    },
+    evaluate: <T>(fn: () => T): Promise<T> => evaluateClosure(page, fn) as unknown as Promise<T>,
+    locator: (selector) => locate({ kind: 'css', selector, first: false }),
+    getByRole: (role, roleOptions) =>
+      locate({
+        kind: 'role',
+        role,
+        first: false,
+        ...(roleOptions?.name === undefined ? {} : { name: roleOptions.name }),
+        ...(roleOptions?.level === undefined ? {} : { level: roleOptions.level }),
+      }),
+    getByText: (text) => locate({ kind: 'text', text, first: false }),
+  };
+}

package/src/e2e-preload.ts

@@ -0,0 +1,22 @@
+// The e2e step's own preload: when the gate names an app root (`ULTIMATE_E2E_ROOT`, set by
+// `verify-e2e.ts`), spawn that app on a throwaway database and start one run over it
+// (`e2e-run.ts`) with Bun's own hooks and a real browser. With no root named it is INERT.
+
+import { afterAll, beforeEach } from 'bun:test';
+import { openE2eBrowser } from './cdp-browser';
+import { startE2eApp } from './e2e-app';
+import { E2E_ROOT_ENV } from './e2e-browser-handle';
+import { installE2eDriver } from './e2e-driver';
+import { startE2eRun } from './e2e-run';
+
+const root = Bun.env[E2E_ROOT_ENV];
+if (root !== undefined && root !== '') {
+  await startE2eRun({
+    app: await startE2eApp({ root }),
+    // `openE2eBrowser`, never the `IfAvailable` door: the step only names a root after finding one.
+    openBrowser: openE2eBrowser,
+    install: installE2eDriver,
+    beforeEach,
+    afterAll,
+  });
+}

package/src/e2e-probe.ts

@@ -0,0 +1,23 @@
+// Is the browser still answering? One cheap `evaluate('1')` raced against a short budget — the
+// question the e2e preload asks before every test, because a hung browser otherwise costs every
+// later suite one full CDP deadline per call (run 8) instead of one relaunch.
+
+/** `true` when the page evaluated `1` within `ms`; a rejection or a stall is `false`, never a throw. */
+export async function answersWithin(
+  page: { evaluate(expression: string): Promise<unknown> },
+  ms: number,
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stalled = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  const answered = page.evaluate('1').then(
+    () => true,
+    () => false,
+  );
+  try {
+    return await Promise.race([answered, stalled]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/e2e-run.ts

@@ -0,0 +1,87 @@
+// One e2e run: the app spawned, ONE browser opened and installed as the `page` fixture, a deploy
+// wired as a restart of the app, a hung or deployed-under browser relaunched before the next test,
+// and everything released after the last. The preload (`e2e-preload.ts`) is this with Bun's own
+// hooks and the real app and browser; a test is this with doubles, which is how it is measured.
+
+import { finiteCount } from '@ultimat3/core';
+import type { E2eBrowser } from './cdp-browser';
+import type { E2eApp } from './e2e-app';
+import { e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-handle';
+import type { E2eDriverOptions } from './e2e-driver';
+import type { E2eBrowserPage } from './e2e-page';
+import { answersWithin } from './e2e-probe';
+
+/** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
+export const PROBE_MS = 5_000;
+
+/**
+ * The browser, or the app stopped: a browser that would not open left the spawned `x dev` child
+ * running after the suite gave up — `cdp-browser.ts`'s own open-or-release shape, one level up.
+ */
+export async function openOrStop<T>(
+  app: { stop(): Promise<void> },
+  open: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await open();
+  } catch (error) {
+    await app.stop().catch(() => undefined);
+    throw error;
+  }
+}
+
+export interface E2eRunDeps {
+  readonly app: E2eApp;
+  readonly openBrowser: () => Promise<E2eBrowser>;
+  readonly install: (options: E2eDriverOptions) => () => void;
+  readonly beforeEach: (hook: () => Promise<void>) => void;
+  readonly afterAll: (hook: () => Promise<void>) => void;
+  readonly probeMs?: number | undefined;
+}
+
+export async function startE2eRun(deps: E2eRunDeps): Promise<void> {
+  const probeMs = finiteCount('startE2eRun', 'probeMs', deps.probeMs ?? PROBE_MS, 1);
+  const { app } = deps;
+  let builds = 0;
+  // A deploy leaves the browser holding the OLD build's state: a SharedWorker whose socket went
+  // down with the restart and is now deep in its reconnect backoff, and tabs rendered by the old
+  // build. The test that deployed asserts on exactly that; the NEXT test must not inherit it.
+  let deployed = false;
+  const newBuild = async (): Promise<void> => {
+    deployed = true;
+    builds += 1;
+    await app.restart({ BUILD_ID: `e2e-build-${String(builds)}-${String(Date.now())}` });
+  };
+  let browser = await openOrStop(app, deps.openBrowser);
+  publishE2eRun({ browser, app });
+  // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
+  // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
+  // every test defined before it driving a closed browser.
+  const current: E2eBrowserPage = {
+    url: () => browser.page.url(),
+    goto: (url, options) => browser.page.goto(url, options),
+    evaluate: (expression) => browser.page.evaluate(expression),
+    click: (selector) => browser.page.click(selector),
+    offline: (enabled) => browser.page.offline(enabled),
+  };
+  const uninstall = deps.install({ page: current, baseUrl: app.base, newBuild });
+
+  // A browser that stopped answering takes every later suite down with it, one call deadline per
+  // call (run 8). So each test starts with a short probe, and a browser that fails it — or one a
+  // deploy ran under — is closed and relaunched: the app is untouched, and the test gets a fresh
+  // profile, a fresh SharedWorker and a fresh tab on the same origin.
+  deps.beforeEach(async () => {
+    const alive = !deployed && (await answersWithin(e2eBrowser().page, probeMs));
+    if (alive) return;
+    deployed = false;
+    browser.close();
+    browser = await deps.openBrowser();
+    republishE2eBrowser(browser);
+  });
+
+  deps.afterAll(async () => {
+    uninstall();
+    browser.close();
+    await app.stop();
+  });
+}

package/src/e2e-selection.ts

@@ -0,0 +1,192 @@
+// What an e2e locator SELECTS, as a value, plus the one in-page expression that resolves it.
+// `locator`/`getByRole`/`getByText` are lazy handles, so the selection has to survive as data
+// until something asks a question about it — and only then does it become a string the browser
+// can run.
+
+/** Where the driver parks its click target. Removed again as soon as the click has been made. */
+export const MARK_ATTRIBUTE = 'data-x-e2e';
+
+/** One selection, exactly as the test spelled it. `first` is `.first()`, applied at resolve time. */
+export type E2eSelection =
+  | { readonly kind: 'css'; readonly selector: string; readonly first: boolean }
+  | {
+      readonly kind: 'role';
+      readonly role: string;
+      readonly name?: string | undefined;
+      readonly level?: number | undefined;
+      readonly first: boolean;
+    }
+  | { readonly kind: 'text'; readonly text: string; readonly first: boolean };
+
+/**
+ * What the page answers for one selection. `count` is how many elements matched AFTER `first`
+ * narrowed it, `visible` is about the first match alone, and `marked` says the click target now
+ * carries `MARK_ATTRIBUTE` — three facts in one round trip, because a locator that asked twice
+ * could be answered about two different renders.
+ */
+export interface E2eResolution {
+  readonly count: number;
+  readonly visible: boolean;
+  readonly marked: boolean;
+}
+
+/**
+ * The elements that carry a role IMPLICITLY, so `getByRole('button')` finds a `<button>` that
+ * never wrote the attribute. A `Map` and not an object literal: the key is a role a test typed,
+ * and a computed read of a `Record` answers `Object.prototype` members — the defect
+ * `bun run proto-index` exists for.
+ *
+ * Deliberately not the whole of WAI-ARIA. A role absent from this table still resolves through
+ * its explicit `[role="…"]` attribute, which is why an unknown role is not refused: refusing
+ * `role="feed"` because a table in the framework is short would be the framework deciding an app's
+ * markup is wrong.
+ */
+const IMPLICIT_ROLE_ELEMENTS = new Map<string, readonly string[]>([
+  ['banner', ['header']],
+  ['button', ['button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]']],
+  ['checkbox', ['input[type="checkbox"]']],
+  ['combobox', ['select']],
+  ['contentinfo', ['footer']],
+  ['dialog', ['dialog']],
+  ['form', ['form']],
+  ['heading', ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']],
+  ['img', ['img']],
+  ['link', ['a[href]']],
+  ['list', ['ul', 'ol']],
+  ['listitem', ['li']],
+  ['main', ['main']],
+  ['navigation', ['nav']],
+  ['option', ['option']],
+  ['radio', ['input[type="radio"]']],
+  ['table', ['table']],
+  // `input:not([type])`: an untyped input is a text box — `text` is the default type.
+  [
+    'textbox',
+    [
+      'input:not([type])',
+      'input[type="text"]',
+      'input[type="email"]',
+      'input[type="search"]',
+      'textarea',
+    ],
+  ],
+]);
+
+/** Elements whose text is markup rather than page copy — `getByText` must never land on one. */
+const TEXT_SKIP_TAGS = ['SCRIPT', 'STYLE', 'HEAD', 'TITLE', 'META', 'LINK', 'NOSCRIPT'];
+
+/** A CSS attribute selector takes a double-quoted string, which is what `JSON.stringify` writes. */
+const roleSelector = (role: string): string =>
+  [`[role=${JSON.stringify(role)}]`, ...(IMPLICIT_ROLE_ELEMENTS.get(role) ?? [])].join(',');
+
+/**
+ * The call a test wrote, rebuilt from the selection. Every refusal below quotes it, because
+ * "an e2e locator matched nothing" names no line of the test file and this does.
+ */
+export function selectionCall(selection: E2eSelection): string {
+  const tail = selection.first ? '.first()' : '';
+  if (selection.kind === 'css') return `page.locator(${JSON.stringify(selection.selector)})${tail}`;
+  if (selection.kind === 'text') return `page.getByText(${JSON.stringify(selection.text)})${tail}`;
+  const options = [
+    ...(selection.name === undefined ? [] : [`name: ${JSON.stringify(selection.name)}`]),
+    ...(selection.level === undefined ? [] : [`level: ${String(selection.level)}`]),
+  ];
+  const role = JSON.stringify(selection.role);
+  const suffix = options.length === 0 ? '' : `, { ${options.join(', ')} }`;
+  return `page.getByRole(${role}${suffix})${tail}`;
+}
+
+/**
+ * The candidate list, as a JS expression evaluating to an array of elements.
+ *
+ * `getByRole` and `getByText` are not CSS and cannot be: a role is implicit in a tag name, an
+ * accessible name comes off four different attributes before it comes off the text, and
+ * `getByText` has to pick the INNERMOST element that contains the string. So the union selector
+ * is only the cheap first pass and every rule after it runs in JS, in the page.
+ */
+function candidateSource(selection: E2eSelection): string {
+  if (selection.kind === 'css') return `all(${JSON.stringify(selection.selector)})`;
+  if (selection.kind === 'text') {
+    const needle = JSON.stringify(selection.text.replace(/\s+/g, ' ').trim().toLowerCase());
+    // Innermost FIRST and the skip list second, in that order. Reversed, `<html>` becomes the
+    // innermost survivor of a page whose only copy of the string is inside a `<script>` — the
+    // ancestor inherits the match its own excluded child made, which is worse than not filtering
+    // at all: it reports one match, at the document root, for text no reader can see.
+    return `innermost(all('*').filter((el) => norm(el.textContent).toLowerCase().indexOf(${needle}) !== -1)).filter((el) => ${JSON.stringify(TEXT_SKIP_TAGS)}.indexOf(el.tagName) === -1)`;
+  }
+  const byRole = `all(${JSON.stringify(roleSelector(selection.role))}).filter((el) => { const own = el.getAttribute('role'); return own === null || norm(own).toLowerCase() === ${JSON.stringify(selection.role.toLowerCase())}; })`;
+  const byLevel =
+    selection.level === undefined
+      ? byRole
+      : `${byRole}.filter((el) => level(el) === ${String(selection.level)})`;
+  return selection.name === undefined
+    ? byLevel
+    : `${byLevel}.filter((el) => accName(el).toLowerCase() === ${JSON.stringify(selection.name.replace(/\s+/g, ' ').trim().toLowerCase())})`;
+}
+
+/**
+ * The helpers the candidate source above calls, defined once inside the IIFE.
+ *
+ * `visible` is `display`/`visibility`/`opacity`, which is character for character what
+ * `@ultimat3/scraping`'s `snapshotExpression` computes for `ElementSnapshot.visible`. That is a
+ * COPY and it is the wrong shape: `ScrapeTarget.query()` already answers a snapshot per element
+ * and `ScrapeFrame` does not expose it, so this driver cannot reach the framework's one definition
+ * of visible without an edit to `packages/scraping/src/page.ts`. Mirrored deliberately rather than
+ * invented, so the two cannot disagree about a page until that edit lands.
+ */
+const HELPERS = `
+  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  const all = (sel) => Array.prototype.slice.call(document.querySelectorAll(sel));
+  const innermost = (found) => found.filter((el) => !found.some((other) => other !== el && el.contains(other)));
+  const level = (el) => {
+    const aria = el.getAttribute('aria-level');
+    if (aria !== null) return Number(aria);
+    const tag = el.tagName.toLowerCase();
+    return /^h[1-6]$/.test(tag) ? Number(tag.slice(1)) : undefined;
+  };
+  const accName = (el) => {
+    const label = el.getAttribute('aria-label');
+    if (label !== null && norm(label) !== '') return norm(label);
+    const by = el.getAttribute('aria-labelledby');
+    if (by !== null) {
+      const parts = norm(by).split(' ').map((id) => document.getElementById(id)).filter((n) => n).map((n) => norm(n.textContent));
+      if (norm(parts.join(' ')) !== '') return norm(parts.join(' '));
+    }
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'input') { const v = el.getAttribute('value'); if (v !== null && norm(v) !== '') return norm(v); }
+    if (tag === 'img') { const a = el.getAttribute('alt'); if (a !== null) return norm(a); }
+    const text = norm(el.textContent);
+    if (text !== '') return text;
+    const title = el.getAttribute('title');
+    return title !== null ? norm(title) : '';
+  };`;
+
+/**
+ * Returns JSON TEXT rather than an object, the same bargain `cdp-snapshot.ts` makes: a CDP round
+ * trip serialises the answer anyway, and a string has ONE deserialiser — a schema parse — instead
+ * of an implicit one inside the browser library plus a cast on this side.
+ */
+export function selectionExpression(selection: E2eSelection, mark?: string): string {
+  const marker = mark === undefined ? 'null' : JSON.stringify(mark);
+  return `(() => {${HELPERS}
+  const found = ${candidateSource(selection)};
+  const matches = ${selection.first ? 'found.slice(0, 1)' : 'found'};
+  const el = matches[0];
+  let visible = false;
+  if (el) {
+    const style = getComputedStyle(el);
+    visible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+  }
+  const mark = ${marker};
+  let marked = false;
+  if (mark !== null && el) { el.setAttribute(${JSON.stringify(MARK_ATTRIBUTE)}, mark); marked = true; }
+  return JSON.stringify({ count: matches.length, visible: visible, marked: marked });
+})()`;
+}
+
+/** The CSS the marked element answers to — what `ScrapePage.click` is handed once one is marked. */
+export const markSelector = (mark: string): string => `[${MARK_ATTRIBUTE}=${JSON.stringify(mark)}]`;
+
+/** Undo. Best effort by design: a click that navigated took the whole document with it. */
+export const unmarkExpression = (mark: string): string =>
+  `(() => { const el = document.querySelector(${JSON.stringify(markSelector(mark))}); if (el) el.removeAttribute(${JSON.stringify(MARK_ATTRIBUTE)}); return JSON.stringify(true); })()`;

package/src/e2e-spawn.ts

@@ -0,0 +1,195 @@
+// The e2e app's PROCESS half: spawn it on a free port, wait for `/readyz`, restart it on the same
+// port as a deploy, stop it. Split from `e2e-app.ts`, which owns the DATABASE half (the throwaway
+// state directory, the reset and the seed), so this half runs against any root with an entry —
+// which is what lets a unit test drive it without a Postgres.
+
+// why: the readiness poll must not go through `globalThis.fetch` — inside `bun test` the testing
+// preload SEALS it, and the app's `/readyz` would be refused as egress. `node:http` is not sealed.
+import { get } from 'node:http';
+// why: Bun exposes no path API — the CLI's bin is joined onto its package directory.
+import { dirname, join } from 'node:path';
+import { assert } from '@ultimat3/core';
+import { E2eAppFailedError } from './e2e-errors';
+
+/** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
+export type E2eAppMode = 'dev' | 'serve';
+
+/**
+ * The `x` the APP installed, read off `@ultimat3/cli`'s own `bin` entry and resolved from the app
+ * root — never a global `x`, which may be a different version of the framework, and never beside
+ * this module: `@ultimat3/testing` does not depend on the CLI, and the `import.meta.dir/bin.ts`
+ * this was while the driver lived in cli named a file that does not exist once it moved here.
+ */
+export async function xBin(root: string): Promise<string> {
+  let manifest: string;
+  try {
+    manifest = Bun.resolveSync('@ultimat3/cli/package.json', root);
+  } catch {
+    throw new E2eAppFailedError({
+      step: 'resolve @ultimat3/cli',
+      output: `@ultimat3/cli does not resolve from ${root}`,
+      fix: 'bun add -d @ultimat3/cli   # in the app root: the e2e app is spawned through the CLI the app itself installed',
+    });
+  }
+  const declared: unknown = await Bun.file(manifest).json();
+  const bin =
+    typeof declared === 'object' && declared !== null ? Reflect.get(declared, 'bin') : undefined;
+  const x = typeof bin === 'object' && bin !== null ? Reflect.get(bin, 'x') : undefined;
+  if (typeof x !== 'string') {
+    throw refuse('resolve @ultimat3/cli', `${manifest} declares no "bin": { "x": … } entry`);
+  }
+  return join(dirname(manifest), x);
+}
+const POLL_MS = 250;
+
+export interface SpawnedE2eApp {
+  /** `http://localhost:<port>`, no trailing slash. */
+  readonly base: string;
+  /** Kill the process. Idempotent. */
+  stop(): Promise<void>;
+  /** Kill it and start it again on the SAME port, with `env` added — a deploy. Refused after `stop()`. */
+  restart(env?: Readonly<Record<string, string>>): Promise<void>;
+}
+
+export interface SpawnE2eAppOptions {
+  readonly root: string;
+  readonly mode: E2eAppMode;
+  /** Every spawn's environment, on top of this process's minus `NODE_ENV`. */
+  readonly env: Readonly<Record<string, string>>;
+  /** Already screened finite by the caller. */
+  readonly readyTimeoutMs: number;
+  /** `xBin(root)`, when the caller already resolved it; resolved here otherwise, in `dev` mode only. */
+  readonly bin?: string | undefined;
+}
+
+/** A port nothing holds right now, asked of the OS and handed to the child. */
+const freePort = (): number => {
+  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
+  const port = probe.port ?? 0;
+  probe.stop(true);
+  return port;
+};
+
+/**
+ * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
+ * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only
+ * seam (the demo viewer an app installs instead of a sign-in route) was off and every page 401'd.
+ * The app under e2e is a development app unless the caller's `env` says otherwise.
+ */
+export const inherited = (): Record<string, string | undefined> => {
+  const { NODE_ENV: _node, ...rest } = Bun.env;
+  return { ...rest, ULTIMATE_ENV: 'development' };
+};
+
+export const refuse = (step: string, output: string): E2eAppFailedError =>
+  new E2eAppFailedError({ step, output });
+
+/** Spawn the app and answer once `/readyz` does; refuses with the app's own output tail. */
+export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE2eApp> {
+  const deadline = options.readyTimeoutMs;
+  const port = freePort();
+  // Its own scrape port too: every role opens one, the default is a fixed 9090, and a second app —
+  // or a developer's `x dev` — already holding it is an app that dies at boot with X_PORT_IN_USE.
+  const metricsPort = freePort();
+  const base = `http://localhost:${String(port)}`;
+  const command =
+    options.mode === 'serve'
+      ? ['bun', 'apps/web/server.ts']
+      : ['bun', options.bin ?? (await xBin(options.root)), 'dev', '--port', String(port)];
+  const spawnApp = (extra: Readonly<Record<string, string>>) =>
+    Bun.spawn(command, {
+      cwd: options.root,
+      env: {
+        ...inherited(),
+        ...options.env,
+        METRICS_PORT: String(metricsPort),
+        // The origin the app is actually reachable at. A page that renders a typed client builds
+        // its absolute URLs from it, and without it `/feed` answered 500 with X_ENV_MISSING APP_URL.
+        APP_URL: base,
+        ...(options.mode === 'serve' ? { ROLE: 'web', PORT: String(port) } : {}),
+        ...extra,
+      },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  const ready = async (child: ReturnType<typeof spawnApp>, tail: () => string): Promise<void> => {
+    for (let waited = 0; waited < deadline; waited += POLL_MS) {
+      if (child.exitCode !== null) break;
+      if (await answersOk(`${base}/readyz`)) return;
+      await Bun.sleep(POLL_MS);
+    }
+    child.kill();
+    await child.exited;
+    throw refuse(`${command.join(' ')} never answered ${base}/readyz`, tail());
+  };
+
+  let child = spawnApp({});
+  // Drained from the start and kept bounded: an app's log is unbounded, and a pipe nobody reads
+  // fills its buffer and blocks the child on its next write — an app that "never got ready".
+  let tail = drainTail(child.stdout, child.stderr);
+  let stopped = false;
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    stopped = true;
+    child.kill();
+    await child.exited;
+  };
+  try {
+    await ready(child, tail);
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+  return {
+    base,
+    stop,
+    async restart(next: Readonly<Record<string, string>> = {}): Promise<void> {
+      // `stop()` is final. A child respawned here would be one no later `stop()` kills — the flag
+      // already says done — and `startE2eApp` has deleted the state directory it would boot on.
+      assert(
+        !stopped,
+        'restart() was called on an e2e app that was already stopped, so there is no app to deploy over',
+        'startE2eApp({ root }) again for a fresh app — restart() is for an app that is still running',
+      );
+      // The same port and the same state directory — a deploy, not a second app: a tab already
+      // open on `base` sees the new build on its next request, and the data it wrote is still there.
+      child.kill();
+      await child.exited;
+      child = spawnApp(next);
+      tail = drainTail(child.stdout, child.stderr);
+      await ready(child, tail);
+    },
+  };
+}
+
+const TAIL_CHARS = 16_000;
+
+/** Read both streams to their end in the background; answer the last `TAIL_CHARS` of either. */
+function drainTail(...streams: readonly ReadableStream<Uint8Array>[]): () => string {
+  let text = '';
+  for (const stream of streams) {
+    void (async () => {
+      const decoder = new TextDecoder();
+      for await (const chunk of stream) {
+        text = (text + decoder.decode(chunk, { stream: true })).slice(-TAIL_CHARS);
+      }
+    })().catch(() => undefined);
+  }
+  return () => text;
+}
+
+/** One GET, answered as "2xx or not" — never a throw, and never through the sealed `fetch`. */
+function answersOk(url: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const request = get(url, (response) => {
+      response.resume();
+      const status = response.statusCode ?? 0;
+      resolve(status >= 200 && status < 300);
+    });
+    request.on('error', () => resolve(false));
+    request.setTimeout(POLL_MS * 4, () => {
+      request.destroy();
+      resolve(false);
+    });
+  });
+}