@ultimat3/testing 23.0.0 → 25.0.0

package/src/cdp-browser.ts

@@ -13,11 +13,52 @@ import type { E2eSession } from './cdp-e2e-session';
 import { cdpE2eSession } from './cdp-e2e-session';
 import { CdpBrowserMissingError } from './cdp-errors';
 import type { LaunchedBrowser } from './cdp-launch';
-import { CHROME_CANDIDATES, findChrome, launchChrome } from './cdp-launch';
+import { CHROME_CANDIDATES, findChrome, LAUNCH_BUDGET_MS, launchChrome } from './cdp-launch';
+import { LAUNCHED_CLOSE_MS } from './cdp-launch-attempt';
 
 /** How long a launch, a connect or a single CDP call may take. One number, three deadlines. */
 export const DEFAULT_CDP_TIMEOUT_MS = 30_000;
 
+/**
+ * Sequential deadlines `cdpE2eSession` spends before it answers — `Target.setDiscoverTargets`,
+ * then `Target.setAutoAttach` — and `newTab()` spends per tab: `Target.createTarget`, then the
+ * attach that publishes it. Counts of calls in `cdp-e2e-session.ts`, held to it by
+ * `cdp-browser.test.ts` over a fake connection.
+ */
+export const SESSION_SETUP_DEADLINES = 2;
+export const TAB_OPEN_DEADLINES = 2;
+
+/** The longest one more `session.newTab()` is designed to take, at the default per-call deadline. */
+export const E2E_TAB_OPEN_MS = TAB_OPEN_DEADLINES * DEFAULT_CDP_TIMEOUT_MS;
+
+/**
+ * The longest `openE2eBrowser()` is DESIGNED to take, at the default deadline: the whole launch
+ * budget — both starts and their reaps — then the session's setup and the first tab. THE deadline
+ * for a `beforeAll` or `afterAll` that opens or closes a browser: one below it is killed by Bun
+ * before the relaunch, and the failure that names the slow step never surfaces. Derived, never
+ * restated: `e2e-browser-hooks.test.ts` refuses a browser hook whose deadline does not start here.
+ */
+export const E2E_BROWSER_OPEN_MS =
+  LAUNCH_BUDGET_MS + SESSION_SETUP_DEADLINES * DEFAULT_CDP_TIMEOUT_MS + E2E_TAB_OPEN_MS;
+
+/**
+ * The longest `E2eBrowser.close()` is DESIGNED to take — the launched browser's close, every step
+ * bounded (`LAUNCHED_CLOSE_MS`). THE deadline for a hook that closes a browser it already holds: a
+ * hook left at Bun's 5 s default is killed mid-close, and when it is the run's last the process
+ * exits with the profile half-removed — the `x-e2e-chrome-*` directories found leaked in `/tmp`.
+ */
+export const E2E_BROWSER_CLOSE_MS = LAUNCHED_CLOSE_MS;
+
+/**
+ * Sequential deadlines one `tab.goto()` spends: the load event raced against `Page.navigate`'s
+ * reply (one deadline, two waiters), then the two reads of the document (`cdp-e2e-page.ts`). Held
+ * to the method by `cdp-browser.test.ts` over a fake connection, as the tab's count is.
+ */
+export const GOTO_DEADLINES = 3;
+
+/** The longest one `tab.goto()` is designed to take, at the default per-call deadline. */
+export const E2E_GOTO_MS = GOTO_DEADLINES * DEFAULT_CDP_TIMEOUT_MS;
+
 export interface E2eBrowser {
   /** The first tab — what `installE2eDriver({ page })` drives. */
   readonly page: E2eTab;
@@ -27,13 +68,12 @@ export interface E2eBrowser {
    * drives, on the same launch as `page` — one harness, never a second one beside the driver.
    */
   readonly session: E2eSession;
-  /** Idempotent, and it closes both halves: the CDP socket, then the process and its profile. */
-  close(): void;
   /**
-   * `close()`, resolving once the process has exited (bounded — `CLOSE_GRACE_MS`, then SIGKILL).
-   * Optional so a test double need not model a process; the launched browser always has it.
+   * THE close, idempotent, awaited: the CDP connection, then the process, its process group and its
+   * profile (bounded — `CLOSE_GRACE_MS` per step). Unawaited, a process that exits next leaves a
+   * Chrome child and a profile directory behind.
    */
-  closed?(): Promise<void>;
+  close(): Promise<void>;
 }
 
 export interface OpenE2eBrowserOptions {
@@ -60,10 +100,6 @@ const compose = (launched: LaunchedBrowser, session: E2eSession, page: E2eTab):
   // the process out from under an open connection makes every in-flight call report "the browser
   // closed the CDP connection", which is true and useless.
   close: () => launched.close(),
-  closed: async () => {
-    if (launched.closed === undefined) launched.close();
-    else await launched.closed();
-  },
 });
 
 /**
@@ -107,7 +143,7 @@ async function openLaunched(
     });
     return compose(launched, session, await session.newTab());
   } catch (error) {
-    launched.close();
+    await launched.close();
     throw error;
   }
 }

package/src/cdp-connection.ts

@@ -11,8 +11,9 @@
 // small ones, on Bun's native `WebSocket`, with no dependency to add to a repo whose first
 // non-negotiable is that Bun's natives replace most of them.
 
-import { assert } from '@ultimat3/core';
+import { assert, stringField } from '@ultimat3/core';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { wireWatch } from './cdp-wire-watch';
 
 /** One CDP result. `unknown` because every payload here is somebody else's JSON. */
 export interface CdpResult {
@@ -20,8 +21,17 @@ export interface CdpResult {
 }
 
 export interface CdpConnection {
-  /** Send one command. `sessionId` targets an attached page rather than the browser itself. */
-  send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<CdpResult>;
+  /**
+   * Send one command. `sessionId` targets an attached page rather than the browser itself.
+   * `deadlineMs` replaces the connection's per-call deadline for THIS call — the launcher's first
+   * call is a cold start, not a call, and is the only caller that passes one.
+   */
+  send(
+    method: string,
+    params?: Record<string, unknown>,
+    sessionId?: string,
+    deadlineMs?: number,
+  ): Promise<CdpResult>;
   /**
    * Wait for the next occurrence of one CDP **event**, or for the deadline. Answers `true` when the
    * event arrived and `false` when it did not — it never throws, because every caller has a better
@@ -89,6 +99,16 @@ export interface CdpConnectionOptions {
   readonly timeoutMs: number;
 }
 
+/**
+ * What went wrong, in the socket's own words when it has any. Bun hands `onerror` an `ErrorEvent`
+ * whose `message` is the only place the reason lives — "Failed to connect", "Expected 101 status
+ * code" — and a refusal that drops it names the step and not the cause.
+ */
+const failure = (event: unknown, what: string): string => {
+  const message = stringField(event, 'message');
+  return message === undefined || message === '' ? what : `${what}: ${message}`;
+};
+
 /**
  * A remote browser over its WebSocket url. NOT the e2e driver's wire: measured in the dummy's
  * `offline-feed` suite on Bun 1.4.0, Bun's WebSocket client handed `onmessage` text spliced out of
@@ -115,11 +135,14 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
     };
     // `onerror` is the handshake's only until `listen` below reassigns it: a failure BEFORE open
     // has no pending call to abandon, and rejecting is the only way the caller hears about it.
-    socket.onerror = (): void => {
+    socket.onerror = (event: Event): void => {
       clearTimeout(timer);
       socket.close();
       reject(
-        new CdpCallFailedError({ method: 'connect', detail: 'the browser refused the connection' }),
+        new CdpCallFailedError({
+          method: 'connect',
+          detail: failure(event, 'the browser refused the connection'),
+        }),
       );
     };
   });
@@ -132,7 +155,8 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
         handlers.message(typeof event.data === 'string' ? event.data : '');
       };
       socket.onclose = (): void => handlers.closed('the browser closed the CDP connection');
-      socket.onerror = (): void => handlers.closed('the CDP connection failed');
+      socket.onerror = (event: Event): void =>
+        handlers.closed(failure(event, 'the CDP connection failed'));
     },
   };
   return cdpConnectOver(transport, options.timeoutMs);
@@ -145,6 +169,8 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
   const listeners = new Map<string, Set<CdpEventListener>>();
   let nextId = 0;
   let closed = false;
+  // What a call that is never answered reports instead of a bare "did not answer".
+  const watch = wireWatch();
 
   // Every in-flight call is settled on close. Without this a suite whose browser died waits out
   // one full deadline per call and reports a timeout, where the true fault is a dead browser.
@@ -167,9 +193,12 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
       frame = JSON.parse(raw) as Record<string, unknown>;
     } catch {
       // An unparseable frame is the browser's, not ours, and there is no call to fail with it:
-      // correlation is by `id`, and a frame we cannot read has none. Events land here too.
+      // correlation is by `id`, and a frame we cannot read has none. COUNTED, though: the call
+      // whose reply it was waits out its deadline, and its timeout says frames were dropped.
+      watch.drop();
       return;
     }
+    watch.frame(frame);
     const id = frame['id'];
     if (typeof id !== 'number') {
       const method = frame['method'];
@@ -206,7 +235,7 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
   transport.listen({ message, closed: abandon });
 
   return {
-    send(method, params = {}, sessionId): Promise<CdpResult> {
+    send(method, params = {}, sessionId, deadlineMs = timeoutMs): Promise<CdpResult> {
       if (closed) {
         return Promise.reject(
           new CdpCallFailedError({ method, detail: 'the CDP connection is already closed' }),
@@ -215,10 +244,12 @@ export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpC
       nextId += 1;
       const id = nextId;
       return new Promise<CdpResult>((resolve, reject) => {
+        const sentAt = watch.mark(sessionId);
         const timer = setTimeout(() => {
           pending.delete(id);
-          reject(new CdpTimeoutError({ method, timeoutMs: timeoutMs }));
-        }, timeoutMs);
+          const observed = watch.observe(sentAt, sessionId, !closed);
+          reject(new CdpTimeoutError({ method, timeoutMs: deadlineMs, observed }));
+        }, deadlineMs);
         pending.set(id, { resolve, reject, timer });
         transport.send(
           JSON.stringify({ id, method, params, ...(sessionId === undefined ? {} : { sessionId }) }),

package/src/cdp-e2e-session.ts

@@ -35,11 +35,25 @@ export interface CdpE2eSessionOptions {
   readonly acceptLanguage?: string | undefined;
 }
 
-const POLL_MS = 50;
+/** What a page reports to its own code — the state a test's next `fetch` runs under. */
+const ON_LINE = 'navigator.onLine';
+
+/**
+ * Answers `true` at once when the page already reads `online`, else on the `online`/`offline`
+ * event that flips it. The read and the `addEventListener` run in ONE task, so the event cannot
+ * land between them. `false` only when the event came and the state still disagrees: ask again.
+ */
+const readsOnLine = (online: boolean): string => {
+  const reads = `${ON_LINE} === ${String(online)}`;
+  const flip = online ? 'online' : 'offline';
+  return `${reads} || new Promise((resolve) => addEventListener('${flip}', () => resolve(${reads}), { once: true }))`;
+};
+
+const member = (from: unknown, key: string): unknown =>
+  typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
 
 const field = (from: unknown, key: string): string | undefined => {
-  const value =
-    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  const value = member(from, key);
   return typeof value === 'string' ? value : undefined;
 };
 
@@ -55,6 +69,8 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
   const send = connection.send.bind(connection);
   const sessions = new Set<string>();
   const pages = new Map<string, string>(); // targetId → sessionId
+  // targetId → the `newTab()` waiting for that tab to be published.
+  const published = new Map<string, (session: string) => void>();
   const scripts: string[] = [];
   const sockets: string[] = [];
   const requests: string[] = [];
@@ -137,6 +153,7 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
       const targetId = field(info, 'targetId');
       if (type === 'page' && targetId !== undefined && sessions.has(session)) {
         pages.set(targetId, session);
+        published.get(targetId)?.(session);
       }
     })();
   });
@@ -147,6 +164,86 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
     flatten: true,
   });
 
+  /** Settles `true` on `event` from `session` and `false` at `deadline`, whichever is first. */
+  const nextEvent = (event: string, session: string, deadline: number) => {
+    let heard: () => void = () => undefined;
+    const arrived = new Promise<void>((resolve) => {
+      heard = resolve;
+    });
+    const off = connection.on(event, (_params, on) => {
+      if (on === session) heard();
+    });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return {
+      /** Subscribed when created, so an event that lands before this is awaited still counts. */
+      wait: (): Promise<boolean> =>
+        Promise.race([
+          arrived.then(() => true),
+          new Promise<boolean>((resolve) => {
+            timer = setTimeout(() => resolve(false), Math.max(0, deadline - performance.now()));
+          }),
+        ]),
+      close: (): void => {
+        off();
+        clearTimeout(timer);
+      },
+    };
+  };
+
+  /**
+   * Whether one page came to read `navigator.onLine === online` before `deadline`. The page itself
+   * says when — the evaluated promise resolves on the event that flips it, `awaitPromise` holds the
+   * reply until then — so nothing is polled and nothing sleeps. A navigation destroys the context
+   * the promise lived in and refuses the call; the page is asked again in the document that
+   * replaces it, once Chrome announces that document's context.
+   */
+  const pageReads = async (session: string, online: boolean, deadline: number) => {
+    for (;;) {
+      const remaining = deadline - performance.now();
+      if (remaining <= 0) return false;
+      const context = nextEvent('Runtime.executionContextCreated', session, deadline);
+      try {
+        const answer = await send(
+          'Runtime.evaluate',
+          { expression: readsOnLine(online), returnByValue: true, awaitPromise: true },
+          session,
+          remaining,
+        );
+        const value = member(member(answer.result, 'result'), 'value');
+        if (value === true) return true;
+        // `false`: the event fired and the state disagrees, so the next ask awaits the next one.
+        // Anything else is a page that could not run the read — the same as a refusal, below.
+        if (value !== false && !(await context.wait())) return false;
+      } catch (error) {
+        if (error instanceof CdpTimeoutError) return false;
+        if (!(await context.wait())) return false;
+      } finally {
+        context.close();
+      }
+    }
+  };
+
+  // #572. `offline()` SENDS the condition, and the renderer applies it when it gets to it: a `fetch`
+  // on the caller's next line raced that on a slow runner and went through under a switch the test
+  // had already thrown. So the switch is thrown when every page READS the state, and not before —
+  // never a fixed sleep, which is either too long everywhere or too short on the runner that
+  // matters. Bounded by the load budget, because a page mid-navigation answers only once it lands;
+  // a page that never reads it is a timeout naming the page, never a resolve the test trusts.
+  const confirmed = async (online: boolean): Promise<void> => {
+    const deadline = performance.now() + options.loadTimeoutMs;
+    const open = [...pageSessions].filter((session) => sessions.has(session));
+    const answers = await Promise.all(
+      open.map(async (session) => [session, await pageReads(session, online, deadline)] 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(', ')}`,
+        timeoutMs: options.loadTimeoutMs,
+      });
+    }
+  };
+
   const offline = async (enabled: boolean): Promise<void> => {
     cut = enabled;
     // Sequential, and a session that has gone away is dropped rather than taking the rest down.
@@ -155,21 +252,41 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
     }
     // And `navigator.onLine` from a new document's first script (`cdp-offline-script.ts`) — the
     // network condition alone reaches a reloaded page only after its scripts have run.
+    // A page that is still THERE and refuses is kept and reported once every page has been asked:
+    // dropping it meant every later `offline()` skipped that tab in silence. Only a session the
+    // loop above just found gone is dropped — a closed tab refuses every call.
+    const refused: unknown[] = [];
     for (const session of [...pageSessions]) {
+      if (!sessions.has(session)) {
+        pageSessions.delete(session);
+        continue;
+      }
       const toggled = enabled ? onLineScripts.add(session) : onLineScripts.remove(session);
-      await toggled.catch(() => pageSessions.delete(session));
+      await toggled.catch((error: unknown) => refused.push(error));
     }
+    if (refused.length > 0) throw refused[0];
+    await confirmed(!enabled);
   };
 
-  const attached = async (targetId: string): Promise<string> => {
-    for (let waited = 0; waited < options.loadTimeoutMs; waited += POLL_MS) {
-      const session = pages.get(targetId);
-      if (session !== undefined) return session;
-      await Bun.sleep(POLL_MS);
-    }
-    throw new CdpTimeoutError({
-      method: `Target.attachedToTarget for tab ${targetId}`,
-      timeoutMs: options.loadTimeoutMs,
+  /** The tab's session once it is published — told by the attach itself, never polled for. */
+  const attached = (targetId: string): Promise<string> => {
+    const session = pages.get(targetId);
+    if (session !== undefined) return Promise.resolve(session);
+    return new Promise<string>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        published.delete(targetId);
+        reject(
+          new CdpTimeoutError({
+            method: `Target.attachedToTarget for tab ${targetId}`,
+            timeoutMs: options.loadTimeoutMs,
+          }),
+        );
+      }, options.loadTimeoutMs);
+      published.set(targetId, (ready) => {
+        clearTimeout(timer);
+        published.delete(targetId);
+        resolve(ready);
+      });
     });
   };
 

package/src/cdp-errors.ts

@@ -2,7 +2,7 @@
 // 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';
+import { isFixShellSafe, renderCauseValue, UltimateError } from '@ultimat3/core';
 // Bare: the titles these constructors' codes render with are registered there.
 import './e2e-error-codes';
 
@@ -20,13 +20,66 @@ export class CdpBrowserMissingError extends UltimateError {
   }
 }
 
-/** The binary ran and never announced an endpoint — a crash, a bad flag, or a sandbox refusal. */
+/** One start of the browser that ended without an answer — what `cdp-launch-attempt.ts` reports. */
+export interface CdpLaunchAttempt {
+  /**
+   * `deadline`: alive and silent for `waitedMs`. `closed`: its wire ended, or its dial was
+   * refused, before any answer. `spawn`: the binary could not be started at all — it never ran.
+   */
+  readonly why: 'deadline' | 'closed' | 'spawn';
+  readonly waitedMs: number;
+  /** The code it exited with on its own, or `null` when the launcher had to kill it. */
+  readonly exitCode: number | null;
+  /** The last lines it wrote to stderr; empty when it wrote none. */
+  readonly stderr: string;
+  /**
+   * What the LAUNCHER saw end the attempt, rendered: the refused dial and its endpoint, the call
+   * that timed out, the spawn's own error. Absent on a record that predates it.
+   */
+  readonly detail?: string | undefined;
+}
+
+const HAND_FLAGS =
+  '--headless=new --no-sandbox --disable-dev-shm-usage --disable-gpu --remote-debugging-port=0 about:blank';
+
+const endedText = (attempt: CdpLaunchAttempt): string => {
+  const after = `after ${String(attempt.waitedMs)}ms`;
+  if (attempt.why === 'spawn') return 'could not be started';
+  if (attempt.why === 'deadline')
+    return `no answer inside ${String(attempt.waitedMs)}ms, so it was killed`;
+  return attempt.exitCode === null
+    ? `its DevTools connection ended ${after} without an answer, and it was killed`
+    : `exited with code ${String(attempt.exitCode)} ${after} without answering`;
+};
+
+const attemptText = (attempt: CdpLaunchAttempt, index: number): string => {
+  const saw =
+    attempt.detail === undefined || attempt.detail === ''
+      ? ''
+      : `: ${renderCauseValue(attempt.detail)}`;
+  const said = attempt.stderr === '' ? 'it printed nothing' : renderCauseValue(attempt.stderr);
+  return `launch ${String(index + 1)}: ${endedText(attempt)}${saw}; stderr: ${said}`;
+};
+
+/**
+ * The binary ran and never answered a DevTools call — a crash, a bad flag, a sandbox refusal, or a
+ * machine too loaded to start it inside the launch deadline. Every attempt is in the cause with its
+ * own stderr, because Chrome's start-up noise reads the same in a healthy browser and a dead one:
+ * what tells them apart is whether it EXITED or was still starting when the deadline passed.
+ */
 export class CdpLaunchFailedError extends UltimateError {
-  constructor(input: { readonly executable: string; readonly detail: string }) {
+  constructor(input: {
+    readonly executable: string;
+    readonly attempts: readonly CdpLaunchAttempt[];
+  }) {
+    // Run by hand, a healthy Chrome prints `DevTools listening on ws://…` and a broken one prints
+    // why. A path that is not shell-inert is the operator's own CHROME_PATH — every candidate is.
+    const binary = isFixShellSafe(input.executable) ? input.executable : '"$CHROME_PATH"';
     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',
+      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: it answered no DevTools call in ${String(input.attempts.length)} ${input.attempts.length === 1 ? 'launch' : 'launches, each on its own fresh profile'} — ${input.attempts.map(attemptText).join(' · ')}`,
+      fix: `${binary} ${HAND_FLAGS}`,
+      meta: { executable: input.executable, attempts: input.attempts },
     });
   }
 }
@@ -42,17 +95,85 @@ export class CdpCallFailedError extends UltimateError {
   }
 }
 
+/** How a call's target went away: its session detached, its target was destroyed, or it crashed. */
+export type CdpTargetGone = 'detached' | 'destroyed' | 'crashed';
+
+/** What the wire did between a call being sent and its deadline (`cdp-wire-watch.ts`). */
+export interface CdpTimeoutObservation {
+  /** The session the call was sent on; `null` for a browser-level call. */
+  readonly sessionId: string | null;
+  /** Frames that arrived and parsed after the call was sent — replies to other calls, and events. */
+  readonly framesArrived: number;
+  /** The last of those, oldest first, bounded: `reply <id>`, or `<method> @<session>`. */
+  readonly lastFrames: readonly string[];
+  /** Frames that arrived after the call and could not be parsed. One of them may be its reply. */
+  readonly framesDropped: number;
+  readonly transportOpen: boolean;
+  /** `detached`, `destroyed` or `crashed` when the call's target went away; `null` while it is there. */
+  readonly targetGone: CdpTargetGone | null;
+  /** Main-frame navigations on the call's session since it was sent. */
+  readonly navigations: number;
+}
+
+/** The one-word verdict a reader — or a script over `--json` — branches on. */
+export type CdpTimeoutReading = 'target-gone' | 'lost-in-transport' | 'no-answer';
+
+export const readTimeout = (seen: CdpTimeoutObservation): CdpTimeoutReading =>
+  seen.targetGone !== null
+    ? 'target-gone'
+    : seen.framesDropped > 0
+      ? 'lost-in-transport'
+      : 'no-answer';
+
+const READING: Record<CdpTimeoutReading, (seen: CdpTimeoutObservation) => string> = {
+  'target-gone': (seen) =>
+    `its target is gone (${String(seen.targetGone)}), so nothing was left to answer`,
+  'lost-in-transport': (seen) =>
+    `${String(seen.framesDropped)} frame(s) arrived unparseable after it was sent and were dropped, so its reply may have been lost in transport (${String(seen.framesArrived)} other frame(s) arrived intact)`,
+  'no-answer': (seen) => {
+    if (seen.framesArrived === 0) {
+      return `nothing at all arrived after the call was sent, on a transport that is ${seen.transportOpen ? 'still open' : 'closed'} — the whole browser went silent`;
+    }
+    const moved =
+      seen.navigations === 0
+        ? ''
+        : `; the page navigated ${String(seen.navigations)} time(s) since the call`;
+    return `the target did not answer: ${String(seen.framesArrived)} other frame(s) arrived intact after the call, the last ${renderCauseValue(seen.lastFrames)}${moved}`;
+  },
+};
+
 /**
  * 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.
+ *
+ * `observed` is what the connection saw meanwhile, and it is what tells three failures apart that
+ * all read "did not answer": the target went away, the reply was dropped on the wire, or the target
+ * was there and silent. A deadline the connection did not keep (`waitFor`, the handshake) has none.
  */
 export class CdpTimeoutError extends UltimateError {
-  constructor(input: { readonly method: string; readonly timeoutMs: number }) {
+  constructor(input: {
+    readonly method: string;
+    readonly timeoutMs: number;
+    readonly observed?: CdpTimeoutObservation | undefined;
+  }) {
+    const { observed } = input;
+    const base = `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`;
+    const reading = observed === undefined ? undefined : readTimeout(observed);
     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',
+      cause:
+        observed === undefined || reading === undefined
+          ? base
+          : `${base} — ${READING[reading](observed)}`,
+      fix:
+        reading === undefined || reading === 'no-answer'
+          ? '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'
+          : // `--json`: the rerun's `meta.reading` and `meta.framesDropped` are only printed there.
+            'x test e2e --json',
+      ...(observed === undefined
+        ? {}
+        : { meta: { method: input.method, timeoutMs: input.timeoutMs, reading, ...observed } }),
     });
   }
 }