@ai-ecoverse/slicc-shared-web 1.10.0 → 1.10.1

package/README.md

@@ -65,7 +65,7 @@ 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()`, `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:
+`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 and `chrome.profile` its `slicc-harness-*` profile directory in `$TMPDIR`. `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;
@@ -96,6 +96,13 @@ Why it works the way it does:
 - 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.
 
+## Cleanup
+
+`close()` stops Chrome and removes its profile. A test process that ends without `close()` still leaves nothing running:
+- on `exit` and on `SIGINT`, `SIGTERM` or `SIGHUP`, the harness kills every browser it started in that process with `SIGKILL` and removes its profile and crash dump directory, then re-raises the signal so the process ends the way it would have;
+- when the test process dies of `SIGKILL`, no handler runs. A watchdog, a `sh` that reads a pipe from the test process, then gets end of file and kills Chrome with `SIGKILL` at once. Chrome also runs with `--remote-debugging-pipe` next to the port, so it shuts itself down when that pipe closes, but its shutdown can take seconds. Only the profile stays behind;
+- the first `launch()` in a process removes every `slicc-harness-*` directory in `$TMPDIR` that is older than a day, or older than a minute and no running process uses as its `--user-data-dir`. It never kills a process.
+
 ## Crash dumps
 
 Chrome for Testing runs crashpad by default and ignores `--crash-dumps-dir` and `--enable-crash-reporter`: on Linux it writes every dump to `~/.config/google-chrome-for-testing/Crash Reports/pending/`. `launch` points it at a fresh directory per browser through `BREAKPAD_DUMP_LOCATION`, waits up to 10 s after a crash for crashpad to finish writing, copies the new dumps into the test's artifact directory and deletes the directory on `close()`. Nothing is uploaded.

package/harness/chrome.mjs

@@ -1,8 +1,10 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { execFile, spawn } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { lstat, mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { env as inherited } from 'node:process';
+import { promisify } from 'node:util';
 import { chromium } from 'playwright-core';
 import { cdn } from './cdn.mjs';
 import { CRASHED, connect } from './cdp.mjs';
@@ -16,6 +18,7 @@ import { artifacts, bounded, ignore, sleep, slug, TIMED_OUT } from './util.mjs';
 export const flags = [
   '--headless',
   '--remote-debugging-port=0',
+  '--remote-debugging-pipe',
   '--no-first-run',
   '--no-default-browser-check',
   '--no-sandbox',
@@ -71,7 +74,10 @@ export async function start(
   executable = chromium.executablePath(),
   env = inherited
 ) {
-  const child = spawn(executable, args, { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  const child = spawn(executable, args, {
+    env,
+    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+  });
   const stderr = lines(child.stderr);
   const drained = new Promise((resolve) => child.stderr.once('close', resolve));
   const exited = new Promise((resolve) => {
@@ -110,6 +116,89 @@ export async function stop(cdp, child) {
   }
 }
 
+export const PREFIX = 'slicc-harness-';
+export const DAY = 24 * 60 * 60 * 1000;
+export const GRACE = 60 * 1000;
+
+const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const running = new Set();
+
+function kill(child) {
+  if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+}
+
+function reap() {
+  for (const { children, paths } of running) {
+    for (const child of children) kill(child);
+    for (const path of paths) rmSync(path, { recursive: true, force: true });
+  }
+  running.clear();
+  unhook();
+}
+
+function reraise(signal) {
+  reap();
+  process.kill(process.pid, signal);
+}
+
+function hook() {
+  process.on('exit', reap);
+  for (const signal of signals) process.on(signal, reraise);
+}
+
+function unhook() {
+  process.off('exit', reap);
+  for (const signal of signals) process.off(signal, reraise);
+}
+
+export function watchdog(pid) {
+  const dog = spawn('sh', ['-c', 'read -r _; kill -9 "$0" 2>/dev/null', String(pid)], {
+    stdio: ['pipe', 'ignore', 'ignore'],
+  });
+  dog.on('error', ignore);
+  dog.stdin.on('error', ignore);
+  return dog;
+}
+
+export function track(child, paths) {
+  const dog = watchdog(child.pid);
+  const entry = { children: [child, dog], paths };
+  if (running.size === 0) hook();
+  running.add(entry);
+  return () => {
+    running.delete(entry);
+    if (running.size === 0) unhook();
+    kill(dog);
+  };
+}
+
+export async function commandLines() {
+  const { stdout } = await promisify(execFile)('ps', ['axww', '-o', 'args='], {
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout.split('\n').map((line) => `${line} `);
+}
+
+export async function prune(dir = tmpdir(), grace = GRACE) {
+  const lines = await commandLines().catch(ignore);
+  const used = (path) => lines.some((line) => line.includes(`--user-data-dir=${path} `));
+  const names = await readdir(dir).catch(() => []);
+  const now = Date.now();
+  const removing = names
+    .filter((name) => name.startsWith(PREFIX))
+    .map(async (name) => {
+      const path = join(dir, name);
+      const info = await lstat(path).catch(ignore);
+      if (!info?.isDirectory()) return;
+      const age = now - info.mtimeMs;
+      const orphaned = lines !== null && age > grace && !used(path);
+      if (age > DAY || orphaned) await rm(path, { recursive: true, force: true }).catch(ignore);
+    });
+  await Promise.all(removing);
+}
+
+let pruning = null;
+
 export async function launch({
   roots,
   aliases,
@@ -122,12 +211,14 @@ export async function launch({
   timeout,
   stallAfter,
 } = {}) {
+  pruning ??= prune();
+  await pruning;
   const server = await serve({ roots, aliases, isolated });
   const found = await unpacked(extensions);
   const fromExtension = extensionSource(found);
   const files = { ...server, source: (href) => server.source(href) ?? fromExtension(href) };
   const shared = extensions.length > 0;
-  const profile = await mkdtemp(join(tmpdir(), 'slicc-harness-'));
+  const profile = await mkdtemp(join(tmpdir(), PREFIX));
   const loaded = [...found.values()].map((root) => root.slice(0, -1));
   const dumps = await crashpad();
   const { child, url, exited, stderr } = await start(
@@ -136,6 +227,7 @@ export async function launch({
     chromium.executablePath(),
     dumps.env
   );
+  const untrack = track(child, [profile, dumps.dir]);
   const cdp = await connect(url, {
     exited,
     tail: () => stderr.tail().map((line) => `stderr: ${line}`),
@@ -189,6 +281,7 @@ export async function launch({
   return {
     url: server.url,
     pid: child.pid,
+    profile,
     cdn: remote.state,
     requests: server.requests,
     overrides: server.overrides,
@@ -223,6 +316,7 @@ export async function launch({
     async close() {
       await stop(cdp, child);
       await rm(profile, { recursive: true, force: true });
+      untrack();
       closed = true;
       if (open === 0) await dumps.remove();
       await server.close();

package/package.json

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