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

package/README.md

@@ -59,9 +59,11 @@ 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). `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:
 
@@ -72,4 +74,4 @@ Why it works the way it does:
 - 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) {
@@ -40,7 +76,7 @@ export function fresh() {
   return !window.stale;
 }
 
-export function page(cdp, sessionId, server, timeout = 30000) {
+export function page(cdp, { sessionId, targetId }, server, timeout = 30000) {
   const send = (method, params) => cdp.send(method, params, sessionId);
   const errors = [];
   const responses = [];
@@ -99,6 +135,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/');
   };
 }
 
@@ -180,9 +177,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.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",