@ultimat3/testing 20.2.1 → 22.0.0

package/src/cdp-errors.ts

@@ -0,0 +1,58 @@
+// One constructor per way the raw-CDP e2e browser refuses. Every cause quotes a value that came
+// out of a BROWSER or off a spawned process's stderr, so every one is rendered rather than
+// interpolated — the rule `e2e-errors.ts` already states.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+// Bare: the titles these constructors' codes render with are registered there.
+import './e2e-error-codes';
+
+/**
+ * No browser to drive. This is the one an author meets first, so its fix names the two ways out:
+ * point the driver at a binary, or accept that this machine cannot run the check.
+ */
+export class CdpBrowserMissingError extends UltimateError {
+  constructor(input: { readonly tried: readonly string[] }) {
+    super({
+      code: 'X_CDP_BROWSER_MISSING',
+      cause: `no Chrome or Chromium executable was found — tried ${renderCauseValue(input.tried)}`,
+      fix: 'set CHROME_PATH to a Chrome or Chromium binary (GitHub-hosted ubuntu runners ship one at /usr/bin/google-chrome), or skip the browser-backed e2e suite by leaving it unset',
+    });
+  }
+}
+
+/** The binary ran and never announced an endpoint — a crash, a bad flag, or a sandbox refusal. */
+export class CdpLaunchFailedError extends UltimateError {
+  constructor(input: { readonly executable: string; readonly detail: string }) {
+    super({
+      code: 'X_CDP_LAUNCH_FAILED',
+      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: ${renderCauseValue(input.detail)}`,
+      fix: 'run the same binary by hand with --headless=new --remote-debugging-port=0 and read its stderr; inside a container add --no-sandbox --disable-dev-shm-usage, which this launcher already passes',
+    });
+  }
+}
+
+/** A CDP call answered with an error frame, or the connection died under it. */
+export class CdpCallFailedError extends UltimateError {
+  constructor(input: { readonly method: string; readonly detail: string }) {
+    super({
+      code: 'X_CDP_CALL_FAILED',
+      cause: `the browser refused ${renderCauseValue(input.method)}: ${renderCauseValue(input.detail)}`,
+      fix: 'print what the page had: await page.evaluate(() => document.body.innerHTML) — a call that refuses the same way means the browser itself is gone, so read the launch above it',
+    });
+  }
+}
+
+/**
+ * A call that never answered. Its own code rather than `X_TIMEOUT`, because the actionable half is
+ * WHICH call: a hung `Page.navigate` is an app that never finishes responding, and a hung
+ * `Runtime.evaluate` is an expression that never settles.
+ */
+export class CdpTimeoutError extends UltimateError {
+  constructor(input: { readonly method: string; readonly timeoutMs: number }) {
+    super({
+      code: 'X_CDP_TIMEOUT',
+      cause: `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`,
+      fix: 'raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on — a navigation that never settles is an app that never finishes its response',
+    });
+  }
+}

package/src/cdp-launch.ts

@@ -0,0 +1,192 @@
+// One responsibility: start a Chrome in this container and hand back its DevTools endpoint and the
+// way to stop it. The connection is `cdp-connection.ts` and the page surface `cdp-e2e-page.ts`.
+
+// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
+// directory this launcher must create and delete needs both.
+import { mkdtempSync, rmSync } from 'node:fs';
+// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnectOver } from './cdp-connection';
+import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
+
+/**
+ * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
+ * answer and the only one that can be right on a machine none of the rest describes; the two
+ * `/usr/bin` names after it are what GitHub-hosted `ubuntu-latest` ships, which is what lets the
+ * browser-backed suite run in CI with **no download step and no new dependency**.
+ */
+export const CHROME_PATH_ENV = 'CHROME_PATH';
+export const CHROME_CANDIDATES: readonly string[] = [
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+/** The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure. */
+export async function findChrome(
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string | undefined> {
+  const declared = env[CHROME_PATH_ENV];
+  const candidates = declared === undefined || declared === '' ? CHROME_CANDIDATES : [declared];
+  for (const candidate of candidates) {
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
+ * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
+ * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
+ * a default container, which crashes the renderer on any real page.
+ *
+ * Exported, and in `chromeLaunchFlags` below, so every launcher carries the SAME two. `x shot` had
+ * neither while it launched through `puppeteer-core`, so a box where `x verify`'s e2e gate ran green
+ * could not run `x shot` at all; since 22.0.0 it launches through `launchChrome` here.
+ */
+export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
+
+/**
+ * The flags, and every one of them earns its line.
+ *
+ * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-pipe`
+ * is the wire (`cdp-pipe.ts` says why it is not the WebSocket): no port, so two suites on one
+ * machine can never collide, and nothing but this process can drive the browser. A throwaway
+ * `--user-data-dir` because a run sharing a profile with a real browser inherits its cookies and
+ * locks its files.
+ */
+export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
+  '--headless=new',
+  '--remote-debugging-pipe',
+  `--user-data-dir=${profileDir}`,
+  ...CONTAINER_CHROME_ARGS,
+  '--disable-gpu',
+  // The cookie store's encryption key comes from the OS keyring, asked over D-Bus on the first
+  // cookie access — which is the first navigation. With no keyring answering, Chrome waits out the
+  // D-Bus timeout: measured 7-25 s on the first `Page.navigate` of every launch, against a 30 s CDP
+  // deadline, which is the intermittent `X_CDP_TIMEOUT` of a full e2e run. A throwaway profile has
+  // no secret worth a keyring. `x shot` launches through here too, so it has both.
+  '--password-store=basic',
+  '--use-mock-keychain',
+  // Nothing here should reach the network on its own account, and a first-run bubble or an update
+  // check is a page load the test did not ask for.
+  '--no-first-run',
+  '--no-default-browser-check',
+  '--disable-extensions',
+  'about:blank',
+];
+
+export interface LaunchedBrowser {
+  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
+  readonly connection: CdpConnection;
+  /** Idempotent: closes the connection, kills the process, deletes the profile. */
+  close(): void;
+}
+
+export interface LaunchOptions {
+  readonly executable: string;
+  /** How long Chrome has to answer its first call, and every call's deadline after that. */
+  readonly timeoutMs: number;
+}
+
+const STDERR_TAIL_CHARS = 4_000;
+
+/**
+ * Read stderr to its end for the life of the process, keeping only a bounded tail. A pipe nobody
+ * reads fills, and Chrome's next stderr write then blocks the thread making it — a browser that
+ * stops answering mid-run for a reason no log shows. The tail is the launch-failure diagnostics:
+ * a missing library, a sandbox refusal and a bad flag are all named there and nowhere else.
+ */
+function stderrTail(stream: ReadableStream<Uint8Array>): {
+  readonly text: () => string;
+  /** Settles once the stream has ended — every byte the process wrote has been read. */
+  readonly drained: Promise<void>;
+} {
+  let text = '';
+  const drained = (async () => {
+    const decoder = new TextDecoder();
+    for await (const chunk of stream) {
+      text = (text + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
+    }
+  })().catch(() => undefined);
+  return { text: () => text, drained };
+}
+
+/**
+ * How long a browser that failed its first call gets to finish dying, and its stderr to finish
+ * draining, before the tail is read. The pipe ending and the stderr reader reaching the last line
+ * are two unordered events; read at the first, the reason a browser died was reported as "printed
+ * nothing". Bounded, because a WEDGED browser neither exits nor closes stderr.
+ */
+const FAILURE_DRAIN_MS = 1_000;
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/**
+ * Start Chrome on a throwaway profile and answer once it has answered one CDP call. With a pipe
+ * there is no "DevTools listening" line to wait for — the first reply IS the readiness signal, and
+ * a browser that dies or stays silent before it is `X_CDP_LAUNCH_FAILED` carrying its own stderr.
+ */
+export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
+  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
+  const child = Bun.spawn([options.executable, ...chromeLaunchFlags(profileDir)], {
+    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
+    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+  });
+  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
+  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  const connection = cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    options.timeoutMs,
+  );
+  let closed = false;
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    connection.close();
+    child.kill();
+    rmSync(profileDir, { recursive: true, force: true });
+  };
+  try {
+    await connection.send('Browser.getVersion');
+    return { connection, close };
+  } catch {
+    await within(FAILURE_DRAIN_MS, child.exited);
+    close();
+    await within(FAILURE_DRAIN_MS, tail.drained);
+    const seen = tail.text().trim();
+    throw new CdpLaunchFailedError({
+      executable: options.executable,
+      detail:
+        seen === ''
+          ? 'it answered no DevTools call and printed nothing before the deadline'
+          : seen.split('\n').slice(-3).join(' | '),
+    });
+  }
+}
+
+/** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */
+export async function launchFoundChrome(
+  env: Readonly<Record<string, string | undefined>>,
+  timeoutMs: number,
+): Promise<LaunchedBrowser> {
+  const executable = await findChrome(env);
+  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+  return launchChrome({ executable, timeoutMs });
+}

package/src/cdp-offline-script.ts

@@ -0,0 +1,76 @@
+// One responsibility: `navigator.onLine` reads `false` from a document's FIRST script while the
+// session's offline switch is thrown, and reads `true` again — with the `online` event a page
+// reconnects on — when it goes back. `Network.emulateNetworkConditions` cuts the NETWORK for a
+// document created under the switch but, measured on Chrome 150, never tells it so: a reload under
+// the switch read `navigator.onLine === true` at its first script every time, COOP or not, still
+// read `true` a second later, and got no `online` event when the switch went back.
+// `Network.overrideNetworkState` changed nothing. The dummy's page boot asks at its first script
+// and replayed its outbox with a real POST under the cut (`offline-like.e2e.test.ts`, two attempts).
+//
+// The override is an OWN property on `navigator`, so the real getter on `Navigator.prototype` is one
+// `delete` away. A document Chrome DID tell (it saw `offline`) gets Chrome's own `online` event on
+// restore; one it never told gets one from `RESTORE_ONLINE`, so a page reconnects exactly once.
+
+import type { CdpResult } from './cdp-connection';
+
+type Send = (
+  method: string,
+  params: Record<string, unknown>,
+  session: string,
+) => Promise<CdpResult>;
+
+/** Runs before the page's own scripts, in every document a page session creates while cut. */
+export const OFFLINE_FIRST_SCRIPT = `(() => {
+  let told = false;
+  Object.defineProperty(navigator, 'onLine', { configurable: true, get: () => false });
+  addEventListener('offline', () => { told = true; });
+  addEventListener('online', () => { delete navigator.onLine; }, { once: true });
+  Object.defineProperty(window, '__xRestoreOnLine', { configurable: true, value: () => {
+    if (!Object.getOwnPropertyDescriptor(navigator, 'onLine')) return;
+    delete navigator.onLine;
+    if (!told) dispatchEvent(new Event('online'));
+  } });
+})();`;
+
+/** Evaluated in every open page when the switch goes back: a no-op in a document never cut. */
+export const RESTORE_ONLINE = `window.__xRestoreOnLine?.()`;
+
+export interface OfflineScripts {
+  /** Register the script on one page session, once; answers once the browser has it. */
+  add(session: string): Promise<unknown>;
+  /** Unregister it from one page session, if it holds it, and restore the open document. */
+  remove(session: string): Promise<unknown>;
+}
+
+const field = (from: unknown, key: string): string | undefined => {
+  const value =
+    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  return typeof value === 'string' ? value : undefined;
+};
+
+/** Per-session registration, keyed by the identifier the browser hands back. */
+export function offlineScripts(send: Send): OfflineScripts {
+  const held = new Map<string, string>();
+  return {
+    async add(session) {
+      // Held already: a second `offline(true)` registered a second copy and kept one id, so
+      // `online()` removed one and every new page still read `navigator.onLine === false`.
+      if (held.has(session)) return undefined;
+      const answer = await send(
+        'Page.addScriptToEvaluateOnNewDocument',
+        { source: OFFLINE_FIRST_SCRIPT },
+        session,
+      );
+      const identifier = field(answer.result, 'identifier');
+      if (identifier !== undefined) held.set(session, identifier);
+      return answer;
+    },
+    async remove(session) {
+      const identifier = held.get(session);
+      if (identifier === undefined) return undefined;
+      held.delete(session);
+      await send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session);
+      return send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session);
+    },
+  };
+}

package/src/cdp-pipe.ts

@@ -0,0 +1,77 @@
+// One responsibility: CDP over the pipe `--remote-debugging-pipe` opens — Chrome reads commands on
+// its fd 3 and writes replies and events on its fd 4, each message one JSON text ended by a NUL
+// byte. This is the e2e driver's wire; the WebSocket in `cdp-connection.ts` is for a remote browser.
+//
+// Why a pipe rather than the WebSocket Chrome also offers: Bun 1.4.0's WebSocket client handed
+// `onmessage` text spliced from several frames under the dummy's `offline-feed` load — 64
+// unparseable frames in one run, one of them a `Runtime.evaluate` reply that then waited out its
+// 30 s deadline. A frame nobody can parse has no `id`, so no layer above can even tell which call
+// it lost. A pipe is bytes and a delimiter, read here, and nothing in between.
+
+import type { CdpTransport } from './cdp-connection';
+
+/** The two ends a transport needs: a sink for whole messages, and the byte stream Chrome writes. */
+export interface PipeEnds {
+  /** Write these bytes to Chrome's fd 3, in order. */
+  readonly write: (bytes: Uint8Array) => void;
+  /** Chrome's fd 4. */
+  readonly read: ReadableStream<Uint8Array>;
+  /** Release the write end — Chrome treats its fd 3 closing as the client going away. */
+  readonly end: () => void;
+}
+
+const NUL = 0;
+
+/** Concatenate two byte arrays; the reader only ever holds the unterminated tail. */
+const join = (a: Uint8Array, b: Uint8Array): Uint8Array => {
+  if (a.length === 0) return b;
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+};
+
+export function pipeTransport(ends: PipeEnds): CdpTransport {
+  const encoder = new TextEncoder();
+  let closed = false;
+  const reader = ends.read.getReader();
+  return {
+    send(text: string): void {
+      if (closed) return;
+      const body = encoder.encode(text);
+      const framed = new Uint8Array(body.length + 1);
+      framed.set(body);
+      framed[body.length] = NUL;
+      ends.write(framed);
+    },
+    close(): void {
+      if (closed) return;
+      closed = true;
+      ends.end();
+      void reader.cancel().catch(() => undefined);
+    },
+    listen(handlers): void {
+      void (async () => {
+        // Split on BYTES, decoded per message: a multi-byte character may straddle two reads, and
+        // decoding each read on its own would corrupt it — the failure this file exists to end.
+        const decoder = new TextDecoder();
+        let tail: Uint8Array = new Uint8Array(0);
+        try {
+          for (;;) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            tail = join(tail, value);
+            for (let at = tail.indexOf(NUL); at !== -1; at = tail.indexOf(NUL)) {
+              handlers.message(decoder.decode(tail.subarray(0, at)));
+              tail = tail.subarray(at + 1);
+            }
+          }
+        } catch {
+          // A read that fails is a pipe that is gone — reported as the close it is, below.
+        }
+        closed = true;
+        handlers.closed('the browser closed the CDP pipe');
+      })();
+    },
+  };
+}

package/src/e2e-app.ts

@@ -0,0 +1,106 @@
+// The app an e2e suite drives, spawned on a THROWAWAY state directory: its own embedded database,
+// its own disk, its own dev lock, created per call and removed on `stop()`. Never the developer's
+// `.x/pgdata` — resetting that from a test run destroys the data an `x dev` beside it is using.
+// This file is the DATABASE half; spawning, readiness and the restart are `e2e-spawn.ts`'s.
+
+// why: Bun ships no temp-directory primitive or recursive remove; `tmpdir()` is node:os's alone.
+import { mkdtemp, rm } from 'node:fs/promises';
+// why: Bun exposes no tmpdir() — only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path API — the state dir is joined, not concatenated.
+import { join } from 'node:path';
+import { finiteCount } from '@ultimat3/core';
+import type { E2eAppMode } from './e2e-spawn';
+import { inherited, refuse, spawnE2eApp, xBin } from './e2e-spawn';
+
+export type { E2eAppMode } from './e2e-spawn';
+
+export interface StartE2eAppOptions {
+  /** The app root — the directory holding `app.config.ts`. */
+  readonly root: string;
+  readonly mode?: E2eAppMode | undefined;
+  /**
+   * The arguments after `x db seed`, or `false` for no seeding. Default `['--tier', 'dev']`: every
+   * dev-tier seed, which is what a developer's own `x dev` starts from.
+   */
+  readonly seed?: readonly string[] | false | undefined;
+  /** Extra environment for every process — the reset, the seed and the app. */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /** How long the app may take to answer `/readyz`. */
+  readonly readyTimeoutMs?: number | undefined;
+}
+
+export interface E2eApp {
+  /** `http://localhost:<port>`, no trailing slash. */
+  readonly base: string;
+  /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
+  readonly stateDir: string;
+  /** Kill the app and delete its state directory. Idempotent. */
+  stop(): Promise<void>;
+  /**
+   * Stop the app and start it again on the SAME port and state directory, with `env` added — a
+   * deploy. `{ BUILD_ID: 'b2' }` is a new build the open tabs have not seen (`deploy.newBuild()`).
+   */
+  restart(env?: Readonly<Record<string, string>>): Promise<void>;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 90_000;
+
+function x(bin: string, args: readonly string[], root: string, env: Record<string, string>): void {
+  const run = Bun.spawnSync(['bun', bin, ...args], {
+    cwd: root,
+    env: { ...inherited(), ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  if (run.exitCode !== 0) {
+    throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);
+  }
+}
+
+/**
+ * Reset and seed a fresh state directory, then spawn the app on a free port and wait for `/readyz`.
+ * The reset runs against the throwaway directory, so it is a first migration, never a data loss.
+ */
+export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp> {
+  // Screened FIRST, before a directory or a process exists: `waited < NaN` is false, so a NaN budget would never poll and report a dead app.
+  const deadline = finiteCount(
+    'startE2eApp',
+    'readyTimeoutMs',
+    options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+  );
+  // Before the state directory too: an app that cannot name its `x` leaves nothing behind.
+  const bin = await xBin(options.root);
+  const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
+  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
+  const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
+  try {
+    x(bin, ['db', 'reset'], options.root, env);
+    const seed = options.seed ?? ['--tier', 'dev'];
+    if (seed !== false) x(bin, ['db', 'seed', ...seed], options.root, env);
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+  try {
+    const spawned = await spawnE2eApp({
+      root: options.root,
+      mode: options.mode ?? 'dev',
+      env,
+      bin,
+      readyTimeoutMs: deadline,
+    });
+    return {
+      base: spawned.base,
+      stateDir,
+      restart: (next) => spawned.restart(next),
+      async stop(): Promise<void> {
+        await spawned.stop();
+        await cleanup();
+      },
+    };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}

package/src/e2e-browser-handle.ts

@@ -0,0 +1,55 @@
+// The browser and the app the e2e step opened, reachable from a test file: `e2eBrowser()` and
+// `e2eApp()`. On `globalThis` under one `Symbol.for` key, because the preload and a test may each
+// hold their own copy of this module — the page-client handle's reason, one runtime over.
+
+import type { E2eBrowser } from './cdp-browser';
+import { CdpBrowserMissingError } from './cdp-errors';
+import { CHROME_CANDIDATES } from './cdp-launch';
+import type { E2eApp } from './e2e-app';
+
+/** Set by the e2e step to the app root; the preload spawns that app and opens a browser. */
+export const E2E_ROOT_ENV = 'ULTIMATE_E2E_ROOT';
+
+interface E2eRun {
+  browser: E2eBrowser;
+  readonly app: E2eApp;
+}
+
+const KEY = Symbol.for('ultimate.e2e.run');
+
+export function publishE2eRun(run: E2eRun): void {
+  Object.defineProperty(globalThis, KEY, { value: run, configurable: true });
+}
+
+const current = (): E2eRun | undefined => Reflect.get(globalThis, KEY) as E2eRun | undefined;
+
+/** Swap in a relaunched browser — the app stays; only the dead browser is replaced. */
+export function republishE2eBrowser(browser: E2eBrowser): void {
+  const run = current();
+  if (run !== undefined) run.browser = browser;
+}
+
+const missing = (): CdpBrowserMissingError =>
+  new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+
+/**
+ * The run's browser: `page`, and `session` for a second tab, an init script, the socket and request
+ * log and the offline switch for every worker. Refuses by name outside an e2e run that found one.
+ */
+export function e2eBrowser(): E2eBrowser {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.browser;
+}
+
+/** The app the run spawned: `base`, `stateDir`, and `restart({ BUILD_ID })` — a deploy. */
+export function e2eApp(): E2eApp {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.app;
+}
+
+/** The spawned app's origin, or `undefined` outside an e2e run. */
+export function e2eBaseUrl(): string | undefined {
+  return current()?.app.base;
+}