@ai-ecoverse/slicc-shared-web 1.3.0 → 1.4.1

package/README.md

@@ -59,17 +59,20 @@ test('boots', async (t) => {
 | `coverage` | URL prefixes whose `.js`/`.mjs` scripts count for coverage. `node_modules/` never does. A `.map` next to a file is used | `['/']` |
 | `exits` | `{ urlPath: [regex, ...] }`: a breakpoint on the first line matching each pattern in that worker script, where the harness takes the worker's coverage and profile before it closes itself | none |
 | `intercept` | Remote URL prefixes answered from a disk cache in `node_modules/.cache/` | none |
+| `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, 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)`, `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), `errors`, `responses` and `dir` (the test's artifact directory). `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. `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:
 
 - Playwright detaches from shared workers, which resumes them early, so their coverage started late about half the time. Raw CDP keeps every worker paused until the profiler runs.
-- `debugger;` pauses in `beforeunload` but not in `pagehide` or `pageswap`, so a `beforeunload` hook, installed after `Page.enable`, takes the coverage of a page before it navigates. The pause only answers CDP when the page itself starts the navigation, so `goto` and `reload` go through `location`, never `Page.navigate` or `Page.reload`.
+- `debugger;` pauses in `beforeunload` but not in `pagehide` or `pageswap`, so a `beforeunload` hook, installed after `Page.enable`, takes the coverage of a page before it navigates. The pause only answers CDP when the page itself starts the navigation, so `goto` and `reload` go through `location`, never `Page.navigate` or `Page.reload`. Navigating away from `about:blank` skips the coverage dump so the first real load is not held in `beforeunload` for a useless snapshot.
+- `goto` used to return as soon as the document swapped (`window.stale` cleared), which is before `readyState` is `complete` and before module scripts run. About 1 load in 20 then looked blank to the next assertion. It now waits for a complete, non-blank document.
 - `takePreciseCoverage` resets the counters, so every snapshot is a delta, and all of them are kept and summed.
 - monocart's `add()` from parallel test processes loses data, so each test writes raw JSON and the teardown merges it once.
 - Coverage of a script served from `chrome.overrides` would be mapped onto the file on disk, so a path overridden during a test is left out of that test's coverage.
 - `--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 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.

package/harness/cdp.mjs

@@ -7,8 +7,18 @@ export async function connect(url) {
   const pending = new Map();
   const listeners = new Set();
   let id = 0;
+  const drop = (sessionId, reason) => {
+    for (const [key, call] of pending) {
+      if (call.sessionId !== sessionId) continue;
+      pending.delete(key);
+      call.reject(new Error(`${call.method}: ${reason}`));
+    }
+  };
   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');
     const call = pending.get(message.id);
     pending.delete(message.id);
     if (!call) for (const listener of listeners) listener(message);
@@ -21,7 +31,7 @@ export async function connect(url) {
   return {
     send: (method, params = {}, sessionId) =>
       new Promise((resolve, reject) => {
-        pending.set(++id, { method, resolve, reject });
+        pending.set(++id, { method, sessionId, resolve, reject });
         socket.send(JSON.stringify({ id, method, params, sessionId }));
       }),
     on: (listener) => {

package/harness/chrome.mjs

@@ -5,6 +5,7 @@ import { basename, join } from 'node:path';
 import { chromium } from 'playwright-core';
 import { cdn } from './cdn.mjs';
 import { connect } from './cdp.mjs';
+import { extensionSource, unpacked } from './extensions.mjs';
 import { page } from './page.mjs';
 import { breakpoints, recorder } from './recorder.mjs';
 import { serve } from './server.mjs';
@@ -26,8 +27,20 @@ export const flags = [
   '--window-size=1280,800',
 ];
 
-export async function start(profile, executable = chromium.executablePath()) {
-  const args = [...flags, `--user-data-dir=${profile}`, 'about:blank'];
+export function commandLine(profile, extensions = [], extra = []) {
+  const loaded = extensions.length > 0;
+  const base = loaded ? flags.filter((flag) => flag !== '--disable-extensions') : flags;
+  const load = loaded
+    ? [`--disable-extensions-except=${extensions}`, `--load-extension=${extensions}`]
+    : [];
+  return [...base, ...load, ...extra, `--user-data-dir=${profile}`, 'about:blank'];
+}
+
+export async function start(
+  profile,
+  args = commandLine(profile),
+  executable = chromium.executablePath()
+) {
   const child = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe'] });
   let log = '';
   const url = await new Promise((resolve, reject) => {
@@ -59,13 +72,20 @@ export async function launch({
   coverage,
   exits = {},
   intercept = [],
+  extensions = [],
+  args = [],
   timeout,
 } = {}) {
   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 { child, url } = await start(profile);
+  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 record = recorder(cdp, server, { coverage, exits: await breakpoints(server, exits) });
+  const record = recorder(cdp, files, { coverage, exits: await breakpoints(server, exits) });
   const remote = await cdn(cdp, intercept);
   await cdp.send('Target.setAutoAttach', {
     autoAttach: true,
@@ -73,7 +93,18 @@ export async function launch({
     flatten: true,
   });
 
-  async function finish(pages, browserContextId, dir) {
+  async function tabs() {
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    return targetInfos.filter(({ type }) => type === 'page').map(({ targetId }) => targetId);
+  }
+
+  async function sweep(before) {
+    const added = (await tabs()).filter((targetId) => !before.has(targetId));
+    const closing = added.map((targetId) => cdp.send('Target.closeTarget', { targetId }));
+    await Promise.all(closing.map((sent) => sent.catch(ignore)));
+  }
+
+  async function finish(pages, browserContextId, dir, before) {
     const shots = pages.map((opened, i) =>
       opened.screenshot(new URL(`tab-${i + 1}.png`, dir)).catch(ignore)
     );
@@ -81,7 +112,10 @@ export async function launch({
     await record.end();
     for (const opened of pages) opened.dispose();
     remote.reset();
-    await bounded(cdp.send('Target.disposeBrowserContext', { browserContextId }), 'dispose');
+    const closing = shared
+      ? sweep(before)
+      : cdp.send('Target.disposeBrowserContext', { browserContextId });
+    await bounded(closing, 'dispose');
   }
 
   return {
@@ -93,13 +127,14 @@ export async function launch({
       const suite = slug(basename(t.filePath ?? 'test', '.test.mjs'));
       const dir = new URL(`${suite}/${slug(t.name)}/`, artifacts);
       await mkdir(dir, { recursive: true });
-      const { browserContextId } = await cdp.send('Target.createBrowserContext');
+      const { browserContextId } = shared ? {} : await cdp.send('Target.createBrowserContext');
+      const before = new Set(shared ? await tabs() : []);
       record.begin(browserContextId, dir, `${suite}-${slug(t.name)}`);
       server.requests.length = 0;
       server.overrides.clear();
       server.overridden.clear();
       const pages = [];
-      t.after(() => finish(pages, browserContextId, dir));
+      t.after(() => finish(pages, browserContextId, dir, before));
       const tab = async () => {
         const opened = page(cdp, await record.open(browserContextId), server, timeout);
         pages.push(opened);

package/harness/extensions.mjs

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { join, normalize, sep } from 'node:path';
+
+export function extensionId(input) {
+  const hex = createHash('sha256').update(input).digest('hex').slice(0, 32);
+  return [...hex].map((digit) => String.fromCharCode(97 + Number.parseInt(digit, 16))).join('');
+}
+
+export async function unpacked(dirs) {
+  const found = new Map();
+  for (const dir of dirs) {
+    const root = await realpath(dir);
+    const manifest = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'));
+    const id = extensionId(manifest.key ? Buffer.from(manifest.key, 'base64') : root);
+    found.set(id, `${root}${sep}`);
+  }
+  return found;
+}
+
+export function extensionSource(found) {
+  return (href) => {
+    if (!href.startsWith('chrome-extension://')) return null;
+    const { host, pathname } = new URL(href);
+    const root = found.get(host);
+    return root ? join(root, normalize(decodeURIComponent(pathname))) : null;
+  };
+}

package/harness/page.mjs

@@ -7,21 +7,57 @@ const keys = new Map([
   ['Tab', { code: 'Tab', keyCode: 9, text: '\t' }],
   ['Backspace', { code: 'Backspace', keyCode: 8 }],
   ['Escape', { code: 'Escape', keyCode: 27 }],
+  ['Delete', { code: 'Delete', keyCode: 46 }],
+  ['Insert', { code: 'Insert', keyCode: 45 }],
+  ['Home', { code: 'Home', keyCode: 36 }],
+  ['End', { code: 'End', keyCode: 35 }],
+  ['PageUp', { code: 'PageUp', keyCode: 33 }],
+  ['PageDown', { code: 'PageDown', keyCode: 34 }],
   ['ArrowUp', { code: 'ArrowUp', keyCode: 38 }],
   ['ArrowDown', { code: 'ArrowDown', keyCode: 40 }],
   ['ArrowLeft', { code: 'ArrowLeft', keyCode: 37 }],
   ['ArrowRight', { code: 'ArrowRight', keyCode: 39 }],
-  [' ', { code: 'Space', keyCode: 32, text: ' ' }],
 ]);
+const punctuation = new Map([
+  [' ', ['Space', 32]],
+  [';', ['Semicolon', 186]],
+  ['=', ['Equal', 187]],
+  [',', ['Comma', 188]],
+  ['-', ['Minus', 189]],
+  ['.', ['Period', 190]],
+  ['/', ['Slash', 191]],
+  ['`', ['Backquote', 192]],
+  ['[', ['BracketLeft', 219]],
+  ['\\', ['Backslash', 220]],
+  [']', ['BracketRight', 221]],
+  ["'", ['Quote', 222]],
+]);
+const shifted = new Map(
+  [...'~!@#$%^&*()_+{}|:"<>?'].map((char, i) => [char, "`1234567890-=[]\\;',./"[i]])
+);
+
+function named(key) {
+  const known = keys.get(key);
+  if (known) return known;
+  const fn = /^F(\d{1,2})$/.exec(key);
+  return { code: key, keyCode: fn ? 111 + Number(fn[1]) : 0 };
+}
+
+export function character(char) {
+  const base = shifted.get(char) ?? char.toLowerCase();
+  const upper = base.toUpperCase();
+  if (/^[a-z]$/.test(base))
+    return { code: `Key${upper}`, keyCode: upper.charCodeAt(0), text: char };
+  if (/^\d$/.test(base)) return { code: `Digit${base}`, keyCode: base.charCodeAt(0), text: char };
+  const [code, keyCode] = punctuation.get(base) ?? ['', 0];
+  return { code, keyCode, text: char };
+}
 
 export function keystroke(key, modifiers) {
   const bits = modifiers.reduce((sum, name) => sum | masks[name], 0);
-  const named = keys.get(key);
-  const code = named?.code ?? `Key${key.toUpperCase()}`;
-  const keyCode = named?.keyCode ?? key.toUpperCase().charCodeAt(0);
-  const plain = named ? named.text : key;
-  const text = bits & ~masks.shift ? undefined : plain;
-  return { key, code, windowsVirtualKeyCode: keyCode, modifiers: bits, text };
+  const { code, keyCode, text } = [...key].length === 1 ? character(key) : named(key);
+  const typed = bits & ~masks.shift ? undefined : text;
+  return { key, code, windowsVirtualKeyCode: keyCode, modifiers: bits, text: typed };
 }
 
 export function settle(ms = 1000) {
@@ -37,10 +73,18 @@ export function mark() {
 }
 
 export function fresh() {
-  return !window.stale;
+  return !window.stale && document.readyState === 'complete' && location.href !== 'about:blank';
 }
 
-export function page(cdp, sessionId, server, timeout = 30000) {
+const specials = { Infinity, '-Infinity': -Infinity, NaN, '-0': -0 };
+
+export function decoded({ value, unserializableValue }) {
+  if (unserializableValue === undefined) return value;
+  if (unserializableValue.endsWith('n')) return BigInt(unserializableValue.slice(0, -1));
+  return specials[unserializableValue];
+}
+
+export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
   const send = (method, params) => cdp.send(method, params, sessionId);
   const errors = [];
   const responses = [];
@@ -63,18 +107,24 @@ export function page(cdp, sessionId, server, timeout = 30000) {
       returnByValue: true,
     });
     if (exceptionDetails) throw new Error(exceptionDetails.exception?.description);
-    return result.value;
+    return decoded(result);
   }
 
   async function until(fn, ...args) {
     const deadline = Date.now() + timeout;
     let last;
     while (Date.now() < deadline) {
-      last = await evaluate(fn, ...args).catch((error) => error.message);
-      if (last === true) return;
+      try {
+        last = await evaluate(fn, ...args);
+        if (last) return last;
+      } catch (error) {
+        last = error.message;
+      }
       await sleep(25);
     }
-    throw new Error(`Timed out waiting for ${fn}\nlast result: ${JSON.stringify(last)}`);
+    throw new Error(
+      `Timed out waiting for a truthy result from ${fn}\nlast result: ${JSON.stringify(last)}`
+    );
   }
 
   async function press(key, ...modifiers) {
@@ -84,9 +134,16 @@ export function page(cdp, sessionId, server, timeout = 30000) {
   }
 
   async function navigate(expression) {
-    await evaluate(mark);
-    await send('Runtime.evaluate', { expression });
-    await until(fresh);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      await evaluate(mark);
+      await send('Runtime.evaluate', { expression });
+      try {
+        await until(fresh);
+        return;
+      } catch (error) {
+        if (attempt === 1) throw error;
+      }
+    }
   }
 
   return {
@@ -99,6 +156,7 @@ export function page(cdp, sessionId, server, timeout = 30000) {
     goto: (path) => navigate(`location.assign(${JSON.stringify(new URL(path, server.url).href)})`),
     reload: () => navigate('location.reload()'),
     insert: (text) => send('Input.insertText', { text }),
+    close: () => cdp.send('Target.closeTarget', { targetId }),
     enter: () => press('Enter'),
     async type(text) {
       for (const key of text) await press(key);

package/harness/recorder.mjs

@@ -2,7 +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 { ignore, raw, samples, sleep } from './util.mjs';
+import { bounded, ignore, raw, samples, sleep, TIMED_OUT } from './util.mjs';
 
 const profiled = new Set(['page', 'worker', 'service_worker', 'shared_worker']);
 const nested = { autoAttach: true, waitForDebuggerOnStart: true, flatten: true };
@@ -32,13 +32,10 @@ export async function breakpoints(server, exits) {
 
 export function covered(server, prefixes) {
   return ({ url }) => {
-    if (!url.startsWith(server.url)) return false;
-    const { pathname } = new URL(url);
-    return (
-      /\.m?js$/.test(pathname) &&
-      !pathname.includes('/node_modules/') &&
-      prefixes.some((prefix) => pathname.startsWith(prefix))
-    );
+    if (!server.source(url)) return false;
+    const { pathname, protocol } = new URL(url);
+    const ours = protocol === 'chrome-extension:' || prefixes.some((p) => pathname.startsWith(p));
+    return ours && /\.m?js$/.test(pathname) && !pathname.includes('/node_modules/');
   };
 }
 
@@ -157,7 +154,12 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
   async function paused(sessionId) {
     const target = sessions.get(sessionId);
     if (target?.type === 'worker') await dump(sessionId, target, false);
-    else await checkpoint();
+    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();
+    }
     await cdp.send('Debugger.resume', {}, sessionId).catch(ignore);
   }
 
@@ -180,9 +182,11 @@ export function recorder(cdp, server, { coverage = ['/'], exits = new Map() } =
       url: 'about:blank',
       browserContextId,
     });
-    const sessionId = await tab(targetId).session;
+    const sessionId = await bounded(tab(targetId).session, 'attach');
     tabs.delete(targetId);
-    return sessionId;
+    if (sessionId === TIMED_OUT) throw new Error(`Target.createTarget: ${targetId} never attached`);
+    if (run && !run.context) run.context = sessions.get(sessionId)?.browserContextId;
+    return { sessionId, targetId };
   }
 
   function begin(context, dir, name) {

package/package.json

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