@ai-ecoverse/slicc-shared-web 1.8.0 → 1.9.0

package/README.md

@@ -65,8 +65,14 @@ test('boots', async (t) => {
 | `timeout` | How long `page.until` polls and `page.evaluate` waits, in ms | `30000` |
 | `stallAfter` | How long one evaluation may run before the harness probes the test's targets, in ms | `30000` |
 
-`chrome.page(t)` opens a tab and returns the page API: `goto(path)`, `reload()`, `evaluate(fn, ...args)`, `until(fn, ...args)`, `press(key, ...modifiers)` (a key name like `Enter` or `F5`, or a single character typed with its US-layout key code), `type(text)`, `insert(text)`, `enter()`, `init(fn)` (runs in every new document), `expose(name, handler)` (a binding the page calls with a JSON string), `screenshot(file)`, `tab()` (another tab in the same context), `close()`, `errors`, `responses` and `dir` (the test's artifact directory). `goto` and `reload` wait until the new document is complete and no longer `about:blank`, and retry the navigation once if that never happens. `until` polls until the function returns a truthy value (not only strict `true`) and resolves with that value; the timeout error names the last result. `within(ms, fn, ...args)` is `until` with its own deadline, for a stage that should take a known time. Both stop at the deadline even if one evaluation never answers. Every CDP call has a deadline: `connect(url).send(method, params, sessionId, ms)` rejects with `<method>: no answer in <ms> ms` (60 s unless given), so a stuck page fails its test instead of hanging the run. When one evaluation runs past `stallAfter`, the harness probes once, without interrupting the wait:
-- it adds a `pending` line to `console.log` for every navigation and request of the page that has no answer yet, with its age. Chrome holds CDP messages to a page while a navigation is waiting for its response, so an evaluation that hangs while the page is idle usually means one of these;
+`chrome.page(t)` opens a tab and returns the page API: `goto(path)`, `reload()`, `evaluate(fn, ...args)`, `until(fn, ...args)`, `press(key, ...modifiers)` (a key name like `Enter` or `F5`, or a single character typed with its US-layout key code), `type(text)`, `insert(text)`, `enter()`, `init(fn)` (runs in every new document), `expose(name, handler)` (a binding the page calls with a JSON string), `screenshot(file)`, `tab()` (another tab in the same context), `close()`, `send(method, params, ms)` (a raw CDP call in the tab's session), `errors`, `responses` and `dir` (the test's artifact directory). `chrome.pid` is the browser's process id. `goto` and `reload` wait until the new document is complete and no longer `about:blank`, and retry the navigation once if that never happens. `until` polls until the function returns a truthy value (not only strict `true`) and resolves with that value; the timeout error names the last result. `within(ms, fn, ...args)` is `until` with its own deadline, for a stage that should take a known time. Both stop at the deadline even if one evaluation never answers. Every CDP call has a deadline: `connect(url).send(method, params, sessionId, ms)` rejects with `<method>: no answer in <ms> ms` (60 s unless given), so a stuck page fails its test instead of hanging the run. A crash fails it at once instead:
+- when the browser dies, every pending and later call rejects with `<method>: browser exited with <signal>` (or `with code <n>`);
+- when a renderer crashes, every pending and later call to that target, and to the dedicated workers it started, rejects with `<method>: page renderer crashed (<status>, code <n>) at <url>` (or `worker`, `shared worker`, `service worker`), and `console.log` gets the same line;
+- `until`, `within`, `goto` and `reload` stop retrying and rethrow it;
+- both errors end with the last five lines of the browser's stderr, and each test keeps up to 200 lines it wrote during the test in `chrome-stderr.log`.
+
+ When one evaluation runs past `stallAfter`, the harness probes once, without interrupting the wait:
+- it adds a `pending` line to `console.log` for every navigation and request of the page that has no answer yet, with its age. A worker's script loads in the worker's own session, so its request is left out. Chrome holds CDP messages to a page while a navigation is waiting for its response, so an evaluation that hangs while the page is idle usually means one of these;
 - it saves `stall-<n>.png` (a screenshot of the page, if the renderer still answers) in the test's artifact directory;
 - it saves a CPU profile sample of every page and worker in the test, including workers started by other workers, as `stall-<n>-<target>-<session>.cpuprofile`;
 - it adds a line per target to `console.log`, saying whether that target is running or paused;
@@ -86,3 +92,4 @@ Why it works the way it does:
 - `--disable-extensions --disable-component-extensions-with-background-pages` keeps a Hangouts service worker out of every run.
 - The attach event can arrive before `Target.createTarget` returns, so new tabs wait on a slot keyed by target id.
 - A worker blocked in `Atomics.wait`, or one that is already gone, may never answer; snapshots give up after 3 s, and closing a context or the browser after 10 s. A call to a target that detaches or crashes fails instead of waiting forever, and a new tab that never attaches fails after 10 s.
+- A WebSocket that has closed takes new messages without an error, and a crashed target never answers, so after a crash every call used to wait out its own deadline: a browser that died 4 s in showed up as `no answer` 15 minutes later. The harness now remembers the crash or the exit and fails each call with it.

package/harness/cdp.mjs

@@ -1,6 +1,23 @@
 export const SEND_TIMEOUT = 60000;
+export const CRASHED = 'Harness.targetCrashed';
 
-export async function connect(url) {
+const kinds = {
+  page: 'page',
+  iframe: 'iframe',
+  worker: 'worker',
+  shared_worker: 'shared worker',
+  service_worker: 'service worker',
+};
+
+export function fatal(message) {
+  return Object.assign(new Error(message), { fatal: true });
+}
+
+function grace(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms, 'socket closed').unref());
+}
+
+export async function connect(url, { exited, tail = () => [] } = {}) {
   const socket = new WebSocket(url);
   await new Promise((resolve, reject) => {
     socket.onopen = resolve;
@@ -8,31 +25,79 @@ export async function connect(url) {
   });
   const pending = new Map();
   const listeners = new Set();
+  const targets = new Map();
+  const crashed = new Map();
+  let gone = null;
   let id = 0;
-  const drop = (sessionId, reason) => {
+  const told = (reason) => [reason, ...tail()].join('\n');
+  const drop = (matches, reason, error = Error) => {
     for (const [key, call] of pending) {
-      if (call.sessionId !== sessionId) continue;
+      if (!matches(call)) continue;
       pending.delete(key);
-      call.reject(new Error(`${call.method}: ${reason}`));
+      call.reject(error(`${call.method}: ${reason}`));
+    }
+  };
+  const notify = (message) => {
+    for (const listener of listeners) listener(message);
+  };
+  const crash = (sessionId, status) => {
+    const target = targets.get(sessionId);
+    if (!target || crashed.has(sessionId)) return;
+    const how = status ? ` (${status})` : '';
+    const reason = `${kinds[target.type] ?? target.type} renderer crashed${how} at ${target.url}`;
+    crashed.set(sessionId, reason);
+    drop((call) => call.sessionId === sessionId, told(reason), fatal);
+    notify({ method: CRASHED, sessionId, params: { reason } });
+    for (const [child, { parent, type }] of targets) {
+      if (parent === sessionId && type === 'worker') crash(child, status);
     }
   };
+  const sessionsOf = (targetId) =>
+    [...targets]
+      .filter(([, target]) => target.targetId === targetId)
+      .map(([sessionId]) => sessionId);
+  const track = ({ method, params, sessionId }) => {
+    if (method === 'Target.attachedToTarget')
+      targets.set(params.sessionId, { ...params.targetInfo, parent: sessionId });
+    if (method === 'Target.targetInfoChanged') {
+      for (const session of sessionsOf(params.targetInfo.targetId)) {
+        targets.set(session, { ...targets.get(session), url: params.targetInfo.url });
+      }
+    }
+    if (method === 'Target.detachedFromTarget') {
+      targets.delete(params.sessionId);
+      drop((call) => call.sessionId === params.sessionId, 'target detached');
+    }
+    if (method === 'Inspector.targetCrashed') setTimeout(crash, 200, sessionId);
+    if (method === 'Target.targetCrashed') {
+      const status = `${params.status}, code ${params.errorCode}`;
+      for (const session of sessionsOf(params.targetId)) crash(session, status);
+    }
+  };
+  const die = (reason) => {
+    if (gone) return;
+    gone = reason;
+    drop(() => true, told(reason), fatal);
+  };
   socket.onmessage = ({ data }) => {
     const message = JSON.parse(data);
-    if (message.method === 'Target.detachedFromTarget')
-      drop(message.params.sessionId, 'target detached');
-    if (message.method === 'Inspector.targetCrashed') drop(message.sessionId, 'target crashed');
+    track(message);
     const call = pending.get(message.id);
     pending.delete(message.id);
-    if (!call) for (const listener of listeners) listener(message);
+    if (!call) notify(message);
     else if (message.error) call.reject(new Error(`${call.method}: ${message.error.message}`));
     else call.resolve(message.result);
   };
-  socket.onclose = () => {
-    for (const call of pending.values()) call.reject(new Error(`${call.method}: socket closed`));
-  };
+  socket.onclose = async () => die(await Promise.race([exited ?? 'socket closed', grace(2000)]));
+  void exited?.then(die);
   return {
     send: (method, params = {}, sessionId, ms = SEND_TIMEOUT) =>
       new Promise((resolve, reject) => {
+        const stopped = gone ?? crashed.get(sessionId);
+        if (stopped) {
+          reject(fatal(`${method}: ${told(stopped)}`));
+          return;
+        }
         const key = ++id;
         const timer = setTimeout(() => {
           pending.delete(key);
@@ -49,6 +114,7 @@ export async function connect(url) {
       listeners.add(listener);
       return () => listeners.delete(listener);
     },
+    target: (sessionId) => targets.get(sessionId),
     close: () => socket.close(),
   };
 }

package/harness/chrome.mjs

@@ -9,7 +9,7 @@ import { extensionSource, unpacked } from './extensions.mjs';
 import { page } from './page.mjs';
 import { breakpoints, recorder } from './recorder.mjs';
 import { serve } from './server.mjs';
-import { artifacts, bounded, ignore, slug, TIMED_OUT } from './util.mjs';
+import { artifacts, bounded, ignore, sleep, slug, TIMED_OUT } from './util.mjs';
 
 export const flags = [
   '--headless',
@@ -36,30 +36,67 @@ export function commandLine(profile, extensions = [], extra = []) {
   return [...base, ...load, ...extra, `--user-data-dir=${profile}`, 'about:blank'];
 }
 
+export const KEPT = 200;
+
+export function lines(stream, kept = KEPT) {
+  const last = [];
+  let partial = '';
+  let total = 0;
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    const split = `${partial}${chunk}`.split('\n');
+    partial = split.pop();
+    total += split.length;
+    last.push(...split);
+    last.splice(0, last.length - kept);
+  });
+  return {
+    get total() {
+      return total;
+    },
+    since: (mark) => last.slice(Math.max(0, last.length - (total - mark))),
+    tail: (n = 5) => last.slice(-n),
+  };
+}
+
+export function exitOf(code, signal) {
+  return signal ? `browser exited with ${signal}` : `browser exited with code ${code}`;
+}
+
 export async function start(
   profile,
   args = commandLine(profile),
   executable = chromium.executablePath()
 ) {
   const child = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe'] });
-  let log = '';
+  const stderr = lines(child.stderr);
+  const drained = new Promise((resolve) => child.stderr.once('close', resolve));
+  const exited = new Promise((resolve) => {
+    child.once('exit', (code, signal) => {
+      const reason = exitOf(code, signal);
+      void Promise.race([drained, sleep(1000)]).then(() => resolve(reason));
+    });
+  });
   const url = await new Promise((resolve, reject) => {
-    child.stderr.on('data', (chunk) => {
-      log += chunk;
-      const match = log.match(/DevTools listening on (ws:\/\/\S+)/);
+    child.stderr.on('data', () => {
+      const match = stderr
+        .tail(KEPT)
+        .join('\n')
+        .match(/DevTools listening on (ws:\/\/\S+)/);
       if (match) resolve(match[1]);
     });
     child.once('error', reject);
-    child.once('exit', (code) => reject(new Error(`Chromium exited with ${code}\n${log}`)));
+    void exited.then((reason) => reject(new Error(`${reason}\n${stderr.tail(KEPT).join('\n')}`)));
   });
-  return { child, url };
+  return { child, url, exited, stderr };
 }
 
 export async function stop(cdp, child) {
   const exited = new Promise((resolve) => child.once('exit', resolve));
   await bounded(cdp.send('Browser.close').catch(ignore), 'Browser.close');
   cdp.close();
-  if (child.exitCode === null && (await bounded(exited, 'exit')) === TIMED_OUT) {
+  const running = child.exitCode === null && child.signalCode === null;
+  if (running && (await bounded(exited, 'exit')) === TIMED_OUT) {
     child.kill('SIGKILL');
     await exited;
   }
@@ -84,10 +121,14 @@ export async function launch({
   const shared = extensions.length > 0;
   const profile = await mkdtemp(join(tmpdir(), 'slicc-harness-'));
   const loaded = [...found.values()].map((root) => root.slice(0, -1));
-  const { child, url } = await start(profile, commandLine(profile, loaded, args));
-  const cdp = await connect(url);
+  const { child, url, exited, stderr } = await start(profile, commandLine(profile, loaded, args));
+  const cdp = await connect(url, {
+    exited,
+    tail: () => stderr.tail().map((line) => `stderr: ${line}`),
+  });
   const record = recorder(cdp, files, { coverage, exits: await breakpoints(server, exits) });
   const remote = await cdn(cdp, intercept);
+  await cdp.send('Target.setDiscoverTargets', { discover: true });
   await cdp.send('Target.setAutoAttach', {
     autoAttach: true,
     waitForDebuggerOnStart: true,
@@ -105,7 +146,9 @@ export async function launch({
     await Promise.all(closing.map((sent) => sent.catch(ignore)));
   }
 
-  async function finish(pages, browserContextId, dir, before) {
+  async function finish(pages, browserContextId, dir, before, mark) {
+    const log = stderr.since(mark).map((line) => `${line}\n`);
+    await writeFile(new URL('chrome-stderr.log', dir), log.join(''));
     await bounded(Promise.all(pages.map((opened) => opened.probed())), 'probes', 30000);
     const shots = pages.map((opened, i) =>
       opened.screenshot(new URL(`tab-${i + 1}.png`, dir)).catch(ignore)
@@ -117,11 +160,12 @@ export async function launch({
     const closing = shared
       ? sweep(before)
       : cdp.send('Target.disposeBrowserContext', { browserContextId });
-    await bounded(closing, 'dispose');
+    await bounded(closing.catch(ignore), 'dispose');
   }
 
   return {
     url: server.url,
+    pid: child.pid,
     cdn: remote.state,
     requests: server.requests,
     overrides: server.overrides,
@@ -136,7 +180,8 @@ export async function launch({
       server.overrides.clear();
       server.overridden.clear();
       const pages = [];
-      t.after(() => finish(pages, browserContextId, dir, before));
+      const mark = stderr.total;
+      t.after(() => finish(pages, browserContextId, dir, before, mark));
       const tab = async () => {
         const opened = page(cdp, await record.open(browserContextId), server, timeout, {
           stallAfter,

package/harness/flight.mjs

@@ -30,5 +30,9 @@ export function flights(now = Date.now) {
       .map(({ what, since }) => `pending ${what} for ${((at - since) / 1000).toFixed(1)}s`);
   }
 
-  return { watch, pending };
+  function loaded(targetId) {
+    requests.delete(targetId);
+  }
+
+  return { watch, loaded, pending };
 }

package/harness/page.mjs

@@ -103,6 +103,7 @@ export function page(
   const flying = flights();
   const dispose = cdp.on((message) => {
     const { method, params, sessionId: from } = message;
+    if (method === 'Inspector.workerScriptLoaded') flying.loaded(cdp.target(from)?.targetId);
     if (from !== sessionId) return;
     flying.watch(message);
     if (method === 'Runtime.exceptionThrown') {
@@ -156,6 +157,7 @@ export function page(
         last = await run(fn, args, left);
         if (last) return last;
       } catch (error) {
+        if (error.fatal) throw error;
         last = error.message;
       }
       await sleep(25);
@@ -183,7 +185,7 @@ export function page(
         await until(fresh);
         return;
       } catch (error) {
-        if (attempt === 1) throw error;
+        if (error.fatal || attempt === 1) throw error;
       }
     }
   }
@@ -192,6 +194,7 @@ export function page(
     errors,
     responses,
     dispose,
+    send,
     evaluate,
     until,
     within,

package/harness/recorder.mjs

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, relative } from 'node:path';
 import { cwd } from 'node:process';
 import { pathToFileURL } from 'node:url';
+import { CRASHED } from './cdp.mjs';
 import { trace } from './trace.mjs';
 import { bounded, ignore, raw, samples, sleep, TIMED_OUT } from './util.mjs';
 
@@ -257,6 +258,7 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
       await paused(sessionId);
     }
     if (method === 'Debugger.resumed') pauses.delete(sessionId);
+    if (method === CRASHED) log(sessionId, params.reason);
   });
 
   async function open(browserContextId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-shared-web",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Shared Renovate, Biome, TypeScript, lefthook and GitHub Actions configuration, plus the CDP integration-test harness, for SLICC's web repos",
   "type": "module",
   "license": "Apache-2.0",