@ai-ecoverse/slicc-shared-web 1.5.1 → 1.7.0

package/README.md

@@ -63,8 +63,16 @@ test('boots', async (t) => {
 | `extensions` | Unpacked extension directories to load. Their scripts are covered and profiled like the repo's own, and tests then run in the default browser context, closing their tabs when they end, because Chrome does not run extensions in the per-test contexts | none |
 | `args` | Extra Chromium flags, such as `--host-resolver-rules` or `--ignore-certificate-errors` | none |
 | `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. Downloads of intercepted URLs time out after 60 s and are tried up to three times; a `4xx` is not retried. `chrome.requests` lists the paths the server saw in this test, `chrome.overrides` is a `Map` of paths to bodies served instead of files, and `chrome.cdn` takes `status` (answer every intercepted request with it), `corrupt` (flip the last byte) and lists the intercepted `requests`. All of them reset with each test. `serve(options)` starts the same server on its own, for an `npm start`.
+`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 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;
+- on the first stall, it records a 10 s browser trace as `stall-1-trace.json` (open it in DevTools' Performance panel or Perfetto). The browser collects it with V8 CPU samples per thread, so it shows what a page's main thread is doing even when that thread no longer answers CDP. It also logs each process's CPU time over the window;
+- it adds a line for every debugger pause still held in the browser, in any target, with its id, URL, start time, reason and top call frames.
+
+A pause in one target blocks every page in the same renderer process, so those pause lines name the culprit even when it isn't the page under test. The harness resumes its own coverage pauses (`beforeunload`, worker exits) within 10 s, even when collecting coverage fails. Downloads of intercepted URLs time out after 60 s and are tried up to three times; a `4xx` is not retried. `chrome.requests` lists the paths the server saw in this test, `chrome.overrides` is a `Map` of paths to bodies served instead of files, and `chrome.cdn` takes `status` (answer every intercepted request with it), `corrupt` (flip the last byte) and lists the intercepted `requests`. All of them reset with each test. `serve(options)` starts the same server on its own, for an `npm start`.
 
 Why it works the way it does:
 

package/harness/chrome.mjs

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { chromium } from 'playwright-core';
@@ -75,6 +75,7 @@ export async function launch({
   extensions = [],
   args = [],
   timeout,
+  stallAfter,
 } = {}) {
   const server = await serve({ roots, aliases, isolated });
   const found = await unpacked(extensions);
@@ -105,6 +106,7 @@ export async function launch({
   }
 
   async function finish(pages, browserContextId, dir, before) {
+    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)
     );
@@ -136,7 +138,13 @@ export async function launch({
       const pages = [];
       t.after(() => finish(pages, browserContextId, dir, before));
       const tab = async () => {
-        const opened = page(cdp, await record.open(browserContextId), server, timeout);
+        const opened = page(cdp, await record.open(browserContextId), server, timeout, {
+          stallAfter,
+          stall: async (tag, png) => {
+            if (png) await writeFile(new URL(`${tag}.png`, dir), png).catch(ignore);
+            await bounded(record.stall(dir, tag), tag, 45000);
+          },
+        });
         pages.push(opened);
         return Object.assign(opened, { tab, dir });
       };

package/harness/page.mjs

@@ -84,7 +84,17 @@ export function decoded({ value, unserializableValue }) {
   return specials[unserializableValue];
 }
 
-export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
+export const STALL_AFTER = 30000;
+
+export function page(
+  cdp,
+  { sessionId, targetId },
+  server,
+  timeout = 30000,
+  { stall, stallAfter = STALL_AFTER } = {}
+) {
+  let stalls = 0;
+  const probes = new Set();
   const send = (method, params, ms) => cdp.send(method, params, sessionId, ms);
   const errors = [];
   const responses = [];
@@ -99,15 +109,34 @@ export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
     if (method === 'Network.responseReceived') responses.push(params.response);
   });
 
+  async function capture() {
+    stalls += 1;
+    const tag = `stall-${stalls}`;
+    const shot = await send('Page.captureScreenshot', { format: 'png' }, 10000).catch(() => null);
+    await stall(tag, shot?.data ? Buffer.from(shot.data, 'base64') : null);
+  }
+
+  function probe() {
+    const running = capture().catch(() => undefined);
+    probes.add(running);
+    void running.then(() => probes.delete(running));
+  }
+
   async function run(fn, args, ms) {
     const expression = `(${fn})(...${JSON.stringify(args)})`;
-    const { result, exceptionDetails } = await send(
-      'Runtime.evaluate',
-      { expression, awaitPromise: true, returnByValue: true },
-      ms
-    );
-    if (exceptionDetails) throw new Error(exceptionDetails.exception?.description);
-    return decoded(result);
+    const at = Math.min(stallAfter, Math.max(ms - 1000, ms / 2));
+    const timer = stall ? setTimeout(probe, at) : null;
+    try {
+      const { result, exceptionDetails } = await send(
+        'Runtime.evaluate',
+        { expression, awaitPromise: true, returnByValue: true },
+        ms
+      );
+      if (exceptionDetails) throw new Error(exceptionDetails.exception?.description);
+      return decoded(result);
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
   function evaluate(fn, ...args) {
@@ -161,6 +190,7 @@ export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
     evaluate,
     until,
     within,
+    probed: () => Promise.all(probes),
     press,
     goto: (path) => navigate(`location.assign(${JSON.stringify(new URL(path, server.url).href)})`),
     reload: () => navigate('location.reload()'),

package/harness/recorder.mjs

@@ -65,8 +65,113 @@ async function entry(server, script) {
   };
 }
 
+function frames(params) {
+  return (params.callFrames ?? [])
+    .slice(0, 3)
+    .map(
+      (frame) =>
+        `${frame.functionName || '(anonymous)'} ${pathOf(frame.url) || frame.url}:${frame.location.lineNumber + 1}`
+    )
+    .join(' < ');
+}
+
+async function sample(cdp, pauses, [sessionId, target], dir, tag) {
+  const send = (method) => cdp.send(method, {}, sessionId, 8000);
+  const stopped = await send('Profiler.stop').catch((error) => ({ error }));
+  send('Profiler.start').catch(ignore);
+  const pause = pauses.get(sessionId);
+  const state = pause ? `paused (${pause.reason})` : 'running';
+  if (!stopped.profile) return `${label(target)}: ${state}, no profile (${stopped.error?.message})`;
+  const name = `${tag}-${label(target)}-${sessionId.slice(0, 6)}.cpuprofile`;
+  await writeFile(new URL(name, dir), JSON.stringify(stopped.profile)).catch(ignore);
+  return `${label(target)}: ${state}, profile ${name}`;
+}
+
+function held(pauses) {
+  return [...pauses.values()].map(
+    (pause) =>
+      `paused ${pause.type} ${pause.targetId} ${pause.url} since ${pause.since}: ${pause.reason}`
+  );
+}
+
+function pauseOf(target = {}, params) {
+  return {
+    type: target.type ?? 'unknown',
+    targetId: target.targetId ?? '?',
+    url: target.url ?? '?',
+    since: new Date().toISOString(),
+    reason: `${params.reason}: ${frames(params)}`,
+  };
+}
+
+const TRACED = [
+  'toplevel',
+  'devtools.timeline',
+  'disabled-by-default-devtools.timeline',
+  'v8.execute',
+  'disabled-by-default-v8.cpu_profiler',
+];
+
+async function cpuTimes(cdp) {
+  const { processInfo = [] } = await cdp
+    .send('SystemInfo.getProcessInfo', {}, undefined, 5000)
+    .catch(() => ({}));
+  return new Map(processInfo.map((info) => [`${info.type} ${info.id}`, info.cpuTime]));
+}
+
+export async function trace(cdp, dir, tag, ms = 10000) {
+  const events = [];
+  const done = Promise.withResolvers();
+  const off = cdp.on(({ method, params }) => {
+    if (method === 'Tracing.dataCollected') events.push(...params.value);
+    if (method === 'Tracing.tracingComplete') done.resolve();
+  });
+  try {
+    const before = await cpuTimes(cdp);
+    await cdp.send(
+      'Tracing.start',
+      { traceConfig: { includedCategories: TRACED }, transferMode: 'ReportEvents' },
+      undefined,
+      10000
+    );
+    await sleep(ms);
+    await cdp.send('Tracing.end', {}, undefined, 10000);
+    await bounded(done.promise, 'trace', 20000);
+    const after = await cpuTimes(cdp);
+    await writeFile(new URL(`${tag}-trace.json`, dir), JSON.stringify({ traceEvents: events }));
+    const busy = [...after]
+      .map(([name, time]) => [name, time - (before.get(name) ?? 0)])
+      .filter(([, used]) => used > 0.05)
+      .map(([name, used]) => `${name} ${used.toFixed(1)}s`);
+    return [
+      `trace ${tag}-trace.json (${events.length} events)`,
+      `cpu over ${ms / 1000}s: ${busy.join(', ') || 'none'}`,
+    ];
+  } catch (error) {
+    return [`trace failed: ${error.message}`];
+  } finally {
+    off();
+  }
+}
+
+function claim(run) {
+  if (!run || run.traced) return false;
+  run.traced = true;
+  return true;
+}
+
+function contextOf(sessions, parents, sessionId) {
+  for (let id = sessionId; id; id = parents.get(id)) {
+    const context = sessions.get(id)?.browserContextId;
+    if (context) return context;
+  }
+  return undefined;
+}
+
 export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } = {}) {
   const sessions = new Map();
+  const pauses = new Map();
+  const parents = new Map();
   const tabs = new Map();
   const ours = covered(server, coverage);
   let run = null;
@@ -151,21 +256,45 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
     run.console.push(`${label(target)}: ${line}`);
   }
 
+  async function capture(sessionId, target) {
+    if (target?.type === 'worker') return dump(sessionId, target, false);
+    const { result } = await cdp
+      .send('Runtime.evaluate', { expression: 'location.href', returnByValue: true }, sessionId)
+      .catch(() => ({ result: {} }));
+    if (result?.value && result.value !== 'about:blank') await checkpoint();
+  }
+
   async function paused(sessionId) {
-    const target = sessions.get(sessionId);
-    if (target?.type === 'worker') await dump(sessionId, target, false);
-    else {
-      const { result } = await cdp
-        .send('Runtime.evaluate', { expression: 'location.href', returnByValue: true }, sessionId)
-        .catch(() => ({ result: {} }));
-      if (result?.value && result.value !== 'about:blank') await checkpoint();
+    try {
+      await bounded(capture(sessionId, sessions.get(sessionId)).catch(ignore), 'pause', 10000);
+    } finally {
+      await cdp.send('Debugger.resume', {}, sessionId, 10000).catch(ignore);
     }
-    await cdp.send('Debugger.resume', {}, sessionId).catch(ignore);
+  }
+
+  async function stall(dir, tag) {
+    const first = claim(run);
+    const current = [...sessions].filter(
+      ([sessionId]) => contextOf(sessions, parents, sessionId) === run?.context
+    );
+    const [lines, traced] = await Promise.all([
+      Promise.all(current.map((entry) => sample(cdp, pauses, entry, dir, tag))),
+      first ? trace(cdp, dir, tag) : [],
+    ]);
+    const all = [...lines, ...traced, ...held(pauses)];
+    for (const line of all) run?.console.push(`${tag}: ${line}`);
+    return all;
   }
 
   cdp.on(async ({ method, params, sessionId }) => {
-    if (method === 'Target.attachedToTarget') await attach(params);
-    if (method === 'Target.detachedFromTarget') sessions.delete(params.sessionId);
+    if (method === 'Target.attachedToTarget') {
+      if (sessionId) parents.set(params.sessionId, sessionId);
+      await attach(params);
+    }
+    if (method === 'Target.detachedFromTarget') {
+      sessions.delete(params.sessionId);
+      pauses.delete(params.sessionId);
+    }
     if (method === 'Runtime.consoleAPICalled') {
       const text = params.args.map((arg) => arg.value ?? arg.description).join(' ');
       log(sessionId, `${params.type} ${text}`);
@@ -174,7 +303,11 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
       const { exception, text } = params.exceptionDetails;
       log(sessionId, `uncaught ${exception?.description ?? text}`);
     }
-    if (method === 'Debugger.paused') await paused(sessionId);
+    if (method === 'Debugger.paused') {
+      pauses.set(sessionId, pauseOf(sessions.get(sessionId), params));
+      await paused(sessionId);
+    }
+    if (method === 'Debugger.resumed') pauses.delete(sessionId);
   });
 
   async function open(browserContextId) {
@@ -211,5 +344,5 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
     ]);
   }
 
-  return { open, begin, end };
+  return { open, begin, end, stall };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-shared-web",
-  "version": "1.5.1",
+  "version": "1.7.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",