@arraypress/extension-kit 1.9.0 → 1.10.0

package/src/testing/live-run.js

@@ -0,0 +1,160 @@
+/**
+ * A live checker's run: the command line read (`parseLiveOptions`), the
+ * sites chosen, where the traffic leaves for the internet printed, then each
+ * site visited in a browser with the extension loaded, a few at once (one
+ * browser a slot, launched on first use, passing for a person's), each within
+ * a time limit (a browser whose page ran out of time is replaced), Ctrl-C
+ * closing every browser. What a visit checks, and the report, are the
+ * checker's own.
+ *
+ * @module testing/live-run
+ */
+
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { within } from '../time/time.js';
+import { eachLimited } from '../time/pool.js';
+import { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
+import { launchExtension } from './e2e.js';
+import { exitPoint, parseLiveOptions } from './live.js';
+
+/** @import { BrowserType, Page } from 'playwright' */
+/** @import { LaunchedExtension } from './e2e.js' */
+/** @import { Exit } from './live.js' */
+
+/**
+ * A site a checker visits.
+ *
+ * @typedef {{name: string, url: string, category: string}} LiveSite
+ */
+
+/**
+ * A finished run, for the checker's report.
+ *
+ * @template {LiveSite} S
+ * @template R
+ * @typedef {object} LiveRun
+ * @property {string} dir The report's folder (made empty).
+ * @property {string} started When it started (ISO).
+ * @property {string} finished When it finished (ISO).
+ * @property {Exit | null} exit Where the traffic left.
+ * @property {{locale: string, timezone: string, proxy: string}} browser How the browsers looked.
+ * @property {{site: S, visit: R}[]} results Each site's visit, in the sites' order.
+ */
+
+/**
+ * A live checker's usage text.
+ *
+ * @param {string[]} categories - The categories' ids.
+ * @param {number} concurrency - The default and most sites at once.
+ * @returns {string} The text.
+ */
+export const liveUsage = (categories, concurrency) => `Usage: npm run live -- [options] [word …]
+
+  --only <word>        only pages whose address or name contains it (repeatable; bare words too)
+  --category <id>      only this category (repeatable): ${categories.join(', ')}
+  --concurrency <n>    pages checked at once (default ${concurrency}, at most ${concurrency})
+  --proxy <url>        send everything through this proxy (default: HTTPS_PROXY)
+  --locale <tag>       browser language (default en-GB)
+  --timezone <zone>    browser time zone (default Europe/London)
+  --out <dir>          write the report there (default test/live/report)
+  --help`;
+
+/**
+ * Run a live check: read the command line, visit the chosen sites, give back every visit.
+ * Prints the usage and exits for `--help` (or an option it doesn't know), and exits when no
+ * site matches.
+ *
+ * @template {LiveSite} S
+ * @template R
+ * @param {object} run
+ * @param {BrowserType} run.chromium - Playwright's chromium.
+ * @param {string} run.build - The extension's live test build (every site granted).
+ * @param {string} run.prefix - The browsers' profile prefix.
+ * @param {string} run.root - The extension's repository (the report goes in `test/live/report`).
+ * @param {S[]} run.sites - Every site.
+ * @param {string[]} run.categories - The categories' ids, for the usage.
+ * @param {number} run.pageMs - The most a visit may take.
+ * @param {(browser: LaunchedExtension, page: Page, site: S) => Promise<R>} run.visit - Check one site, on a fresh page.
+ * @param {(site: S, error: string) => R} run.failed - A visit that couldn't finish (`'timed out'`).
+ * @param {(result: {site: S, visit: R}) => void} [run.onResult] - Each visit as it finishes (a line of output).
+ * @param {{argv?: string[], env?: Record<string, string | undefined>, concurrency?: number, findExit?: typeof exitPoint}} [run.command] - The
+ *   arguments and environment (default the process's), the most sites at once (default 4), and how the exit point
+ *   is found (default `exitPoint`, which asks a lookup service).
+ * @returns {Promise<LiveRun<S, R>>} The run.
+ * @example
+ * const run = await runLiveCheck({ chromium, build: BUILDS.live, prefix: 'better-colors-live-', root, sites: allSites(),
+ *   categories: CATEGORIES.map((c) => c.id), pageMs: 120_000, visit: (browser, page, site) => visit(browser, page, site.url),
+ *   failed: (site, error) => ({ url: site.url, error }), onResult: (result) => console.log(pageLine(result)) });
+ */
+export async function runLiveCheck({ chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult = () => {}, command = {} }) {
+  const { argv = process.argv.slice(2), env = process.env, concurrency = 4, findExit = exitPoint } = command;
+  const usage = liveUsage(categories, concurrency);
+  /** @type {import('./live.js').LiveOptions} */
+  let options;
+  try {
+    options = parseLiveOptions(argv, env, { usage, concurrency, maxConcurrency: concurrency });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+  }
+  if (options.help) {
+    console.log(usage);
+    process.exit(0);
+  }
+  const words = options.only.map((word) => word.toLowerCase());
+  const chosen = sites.filter((site) => (!options.categories.length || options.categories.includes(site.category))
+    && (!words.length || words.some((word) => site.url.toLowerCase().includes(word) || site.name.toLowerCase().includes(word))));
+  if (!chosen.length) {
+    console.error('No pages match.');
+    process.exit(2);
+  }
+  const dir = options.out ? path.resolve(options.out) : path.join(root, 'test', 'live', 'report');
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+
+  const browserOptions = realisticBrowser(options.proxy ? { proxy: options.proxy } : {});
+  const plain = await chromium.launch({ channel: 'chromium', ...browserOptions });
+  /** @type {(LaunchedExtension | null)[]} */
+  const browsers = [];
+  const closeAll = async () => {
+    await Promise.allSettled([plain.close(), ...browsers.map((launched) => launched?.close())]);
+  };
+  const forget = closeOnSignal(closeAll);
+  try {
+    const userAgent = await chromeUserAgent(plain);
+    const probe = await plain.newContext();
+    const exit = await findExit(probe.request);
+    await probe.close();
+    console.log(exit ? `Exit: ${exit.country} (${exit.ip}${exit.where ? `, ${exit.where}` : ''})${options.proxyLabel ? ` through ${options.proxyLabel}` : ''}` : 'Exit: unknown');
+    console.log(`Pages: ${chosen.length}, ${options.concurrency} at a time.\n`);
+    const launchOptions = { ...browserOptions, userAgent, locale: options.locale, timezoneId: options.timezone, viewport: { width: 1280, height: 900 } };
+    const started = new Date().toISOString();
+    /** @type {{site: S, visit: R}[]} */
+    const results = [];
+    await eachLimited(chosen, options.concurrency, async (site, slot, index) => {
+      browsers[slot] ??= await launchExtension(chromium, build, { prefix: `${prefix}${slot}-`, ...launchOptions });
+      const launched = /** @type {LaunchedExtension} */ (browsers[slot]);
+      await within(launched.context.clearCookies(), 10_000, undefined);
+      const page = await launched.context.newPage();
+      const result = await within(visit(launched, page, site), pageMs, undefined);
+      const timedOut = result === undefined;
+      await within(page.close(), 15_000, undefined);
+      if (timedOut) {
+        // A page that ran out of time may have left its browser stuck: the slot gets a new one.
+        await within(launched.close(), 15_000, undefined);
+        browsers[slot] = null;
+      }
+      results[index] = { site, visit: timedOut ? failed(site, 'timed out') : /** @type {R} */ (result) };
+      onResult(results[index]);
+    });
+    return {
+      dir, started, finished: new Date().toISOString(), exit,
+      browser: { locale: options.locale, timezone: options.timezone, proxy: options.proxyLabel },
+      results: results.filter(Boolean),
+    };
+  } finally {
+    forget();
+    await closeAll();
+  }
+}

package/src/testing/pages.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Reaching a tested extension's pages from an e2e test: a Playwright page's
+ * tab id (as the extension's worker sees it), a page module called in a
+ * tab's frames as the extension calls it, and a page's whole tree through
+ * the DevTools protocol, closed shadow roots and frames included (where an
+ * extension's overlay lives). Tests only: an extension never needs CDP.
+ *
+ * @module testing/pages
+ */
+import type { CDPSession, Page, Worker } from 'playwright';
+/** @import { CDPSession, Page, Worker } from 'playwright' */
+/**
+ * The tab id of a page: the newest tab at its address (any tab for a `chrome:` page).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {Page} page - The page.
+ * @returns {Promise<number>} Its tab's id.
+ * @example
+ * const tabId = await tabIdOf(worker, page);
+ */
+export declare function tabIdOf(worker: Worker, page: Page): Promise<number>;
+/**
+ * Call an export of the extension's page module in a tab's frames, as `callInPage` does from the
+ * worker.
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module's path in the extension (`content/main.js`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<{frameId: number, result: any}[]>} Each frame's answer.
+ * @example
+ * const [{ result }] = await callTabModule(worker, tabId, 'content/main.js', 'scan');
+ */
+export declare function callTabModule(worker: Worker, tabId: number, module: string, name: string, args?: unknown[]): Promise<{
+    frameId: number;
+    result: any;
+}[]>;
+export type CdpNode = {
+    /**
+     * Its id in the session.
+     */
+    nodeId: number;
+    /**
+     * Its lasting id.
+     */
+    backendNodeId: number;
+    /**
+     * Its DOM node type.
+     */
+    nodeType: number;
+    /**
+     * Its name.
+     */
+    nodeName: string;
+    /**
+     * A text node's text.
+     */
+    nodeValue?: string;
+    /**
+     * Its attributes, name and value in turn.
+     */
+    attributes?: string[];
+    /**
+     * Its children.
+     */
+    children?: CdpNode[];
+    /**
+     * Its shadow roots, closed ones too.
+     */
+    shadowRoots?: CdpNode[];
+    /**
+     * A frame's document.
+     */
+    contentDocument?: CdpNode;
+};
+/**
+ * A node as the DevTools protocol's `DOM.getDocument` gives it (the parts read here).
+ *
+ * @typedef {object} CdpNode
+ * @property {number} nodeId Its id in the session.
+ * @property {number} backendNodeId Its lasting id.
+ * @property {number} nodeType Its DOM node type.
+ * @property {string} nodeName Its name.
+ * @property {string} [nodeValue] A text node's text.
+ * @property {string[]} [attributes] Its attributes, name and value in turn.
+ * @property {CdpNode[]} [children] Its children.
+ * @property {CdpNode[]} [shadowRoots] Its shadow roots, closed ones too.
+ * @property {CdpNode} [contentDocument] A frame's document.
+ */
+/**
+ * Every node of a page's tree in tree order, closed shadow roots and same-process frames included.
+ *
+ * @param {CDPSession} cdp - A session on the page.
+ * @returns {Promise<CdpNode[]>} The nodes; a node's shadow roots come before its children.
+ * @example
+ * const boxes = (await pierceNodes(cdp)).filter((node) => nodeAttribute(node, 'class') === 'box');
+ */
+export declare function pierceNodes(cdp: CDPSession): Promise<CdpNode[]>;
+/**
+ * A node's attribute.
+ *
+ * @param {CdpNode} node - The node.
+ * @param {string} name - The attribute.
+ * @returns {string} Its value, or ''.
+ */
+export declare function nodeAttribute(node: CdpNode, name: string): string;
+/**
+ * A node's text: a text node's own, an element's children's joined.
+ *
+ * @param {CdpNode} node - The node.
+ * @returns {string} Its text.
+ */
+export declare const nodeText: (node: CdpNode) => string;

package/src/testing/pages.js

@@ -0,0 +1,109 @@
+/**
+ * Reaching a tested extension's pages from an e2e test: a Playwright page's
+ * tab id (as the extension's worker sees it), a page module called in a
+ * tab's frames as the extension calls it, and a page's whole tree through
+ * the DevTools protocol, closed shadow roots and frames included (where an
+ * extension's overlay lives). Tests only: an extension never needs CDP.
+ *
+ * @module testing/pages
+ */
+
+/** @import { CDPSession, Page, Worker } from 'playwright' */
+
+/**
+ * The tab id of a page: the newest tab at its address (any tab for a `chrome:` page).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {Page} page - The page.
+ * @returns {Promise<number>} Its tab's id.
+ * @example
+ * const tabId = await tabIdOf(worker, page);
+ */
+export async function tabIdOf(worker, page) {
+  return worker.evaluate(async (url) => {
+    const query = url.startsWith('chrome:') ? {} : { url: url.replace(/#.*$/, '') };
+    const ids = (await chrome.tabs.query(query)).map((tab) => tab.id ?? -1);
+    if (!ids.length) throw new Error(`No tab for ${url}`);
+    return Math.max(...ids);
+  }, page.url());
+}
+
+/**
+ * Call an export of the extension's page module in a tab's frames, as `callInPage` does from the
+ * worker.
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @param {number} tabId - The tab.
+ * @param {string} module - The module's path in the extension (`content/main.js`).
+ * @param {string} name - The export.
+ * @param {unknown[]} [args] - Its arguments.
+ * @returns {Promise<{frameId: number, result: any}[]>} Each frame's answer.
+ * @example
+ * const [{ result }] = await callTabModule(worker, tabId, 'content/main.js', 'scan');
+ */
+export function callTabModule(worker, tabId, module, name, args = []) {
+  return worker.evaluate(({ tabId, module, name, args }) => chrome.scripting.executeScript({
+    target: { tabId, allFrames: true },
+    injectImmediately: true,
+    // As the kit's importAndCall (a worker's evaluate takes no function from outside, and its CSP no eval).
+    func: (/** @type {string} */ module, /** @type {string} */ name, /** @type {unknown[]} */ args) => import(chrome.runtime.getURL(module)).then((loaded) => loaded[name](...args)),
+    args: [module, name, args],
+  }).then((frames) => frames.map(({ frameId, result }) => ({ frameId, result }))), { tabId, module, name, args });
+}
+
+/**
+ * A node as the DevTools protocol's `DOM.getDocument` gives it (the parts read here).
+ *
+ * @typedef {object} CdpNode
+ * @property {number} nodeId Its id in the session.
+ * @property {number} backendNodeId Its lasting id.
+ * @property {number} nodeType Its DOM node type.
+ * @property {string} nodeName Its name.
+ * @property {string} [nodeValue] A text node's text.
+ * @property {string[]} [attributes] Its attributes, name and value in turn.
+ * @property {CdpNode[]} [children] Its children.
+ * @property {CdpNode[]} [shadowRoots] Its shadow roots, closed ones too.
+ * @property {CdpNode} [contentDocument] A frame's document.
+ */
+
+/**
+ * Every node of a page's tree in tree order, closed shadow roots and same-process frames included.
+ *
+ * @param {CDPSession} cdp - A session on the page.
+ * @returns {Promise<CdpNode[]>} The nodes; a node's shadow roots come before its children.
+ * @example
+ * const boxes = (await pierceNodes(cdp)).filter((node) => nodeAttribute(node, 'class') === 'box');
+ */
+export async function pierceNodes(cdp) {
+  const { root } = /** @type {{root: CdpNode}} */ (await cdp.send('DOM.getDocument', { depth: -1, pierce: true }));
+  /** @type {CdpNode[]} */
+  const nodes = [];
+  /** @param {CdpNode} node */
+  const walk = (node) => {
+    nodes.push(node);
+    for (const child of [...(node.shadowRoots ?? []), ...(node.children ?? []), ...(node.contentDocument ? [node.contentDocument] : [])]) walk(child);
+  };
+  walk(root);
+  return nodes;
+}
+
+/**
+ * A node's attribute.
+ *
+ * @param {CdpNode} node - The node.
+ * @param {string} name - The attribute.
+ * @returns {string} Its value, or ''.
+ */
+export function nodeAttribute(node, name) {
+  const attributes = node.attributes ?? [];
+  const at = attributes.findIndex((value, index) => index % 2 === 0 && value === name);
+  return at >= 0 ? attributes[at + 1] : '';
+}
+
+/**
+ * A node's text: a text node's own, an element's children's joined.
+ *
+ * @param {CdpNode} node - The node.
+ * @returns {string} Its text.
+ */
+export const nodeText = (node) => (node.nodeType === 3 ? node.nodeValue ?? '' : (node.children ?? []).map(nodeText).join(''));

package/src/ui/notice.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A notice in a side panel's list (chrome-ui.css `.sp-notice`): a card with an icon, a heading,
+ * a line, buttons beside the heading and actions under the line. For what a list leaves out or
+ * can't do: frames from other sites to allow, a web font that didn't load.
+ *
+ * @module ui/notice
+ */
+export type Notice = {
+    /**
+     * Its sprite symbol's id.
+     */
+    icon: string;
+    /**
+     * An information's icon is grey, a warning's red. Default `warning`.
+     */
+    tone?: 'info' | 'warning';
+    /**
+     * The heading.
+     */
+    title: string;
+    /**
+     * The line under it.
+     */
+    text: string;
+    /**
+     * Icon buttons at the heading's end.
+     */
+    buttons?: HTMLElement[];
+    /**
+     * Buttons under the line, at the end (“Allow”).
+     */
+    actions?: HTMLElement[];
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+/**
+ * A notice's parts.
+ *
+ * @typedef {object} Notice
+ * @property {string} icon Its sprite symbol's id.
+ * @property {'info' | 'warning'} [tone] An information's icon is grey, a warning's red. Default `warning`.
+ * @property {string} title The heading.
+ * @property {string} text The line under it.
+ * @property {HTMLElement[]} [buttons] Icon buttons at the heading's end.
+ * @property {HTMLElement[]} [actions] Buttons under the line, at the end (“Allow”).
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A notice card.
+ *
+ * @param {Notice} notice - Its parts.
+ * @returns {HTMLElement} The card.
+ * @example
+ * notices.append(noticeCard({ icon: 'i-frame', tone: 'info', title: t('panelFrames'), text, actions: [allow] }));
+ */
+export declare function noticeCard({ icon, tone, title, text, buttons, actions, doc }: Notice): HTMLElement;

package/src/ui/notice.js

@@ -0,0 +1,43 @@
+/**
+ * A notice in a side panel's list (chrome-ui.css `.sp-notice`): a card with an icon, a heading,
+ * a line, buttons beside the heading and actions under the line. For what a list leaves out or
+ * can't do: frames from other sites to allow, a web font that didn't load.
+ *
+ * @module ui/notice
+ */
+
+import { make, spriteIcon } from '../dom/make.js';
+
+/**
+ * A notice's parts.
+ *
+ * @typedef {object} Notice
+ * @property {string} icon Its sprite symbol's id.
+ * @property {'info' | 'warning'} [tone] An information's icon is grey, a warning's red. Default `warning`.
+ * @property {string} title The heading.
+ * @property {string} text The line under it.
+ * @property {HTMLElement[]} [buttons] Icon buttons at the heading's end.
+ * @property {HTMLElement[]} [actions] Buttons under the line, at the end (“Allow”).
+ * @property {Document} [doc] The page. Default `document`.
+ */
+
+/**
+ * A notice card.
+ *
+ * @param {Notice} notice - Its parts.
+ * @returns {HTMLElement} The card.
+ * @example
+ * notices.append(noticeCard({ icon: 'i-frame', tone: 'info', title: t('panelFrames'), text, actions: [allow] }));
+ */
+export function noticeCard({ icon, tone = 'warning', title, text, buttons = [], actions = [], doc = document }) {
+  const card = make('section', `sp-card sp-notice ${tone}`, '', doc);
+  const heading = make('div', 'sp-heading', '', doc);
+  heading.append(spriteIcon(icon, '', doc), make('h2', '', title, doc), ...buttons);
+  card.append(heading, make('p', 'sp-notice-text', text, doc));
+  if (actions.length) {
+    const row = make('div', 'sp-notice-actions', '', doc);
+    row.append(...actions);
+    card.append(row);
+  }
+  return card;
+}