@arraypress/extension-kit 1.2.0 → 1.4.0

package/src/index.js

@@ -1,7 +1,8 @@
 /**
  * The kit's browser half: what an extension's pages, offscreen document and
  * service worker load, Chrome's page components (the ⋮ menu, the one-field
- * dialog, the toast with Undo) included. Every function takes the `chrome`
+ * dialog, the toast with Undo, a settings card's site list) and per-site
+ * lists' sites included. Every function takes the `chrome`
  * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
@@ -13,17 +14,24 @@
 
 export { githubAboutLinks, isPlaceholder } from './about/links.js';
 export { setShortcuts } from './commands/shortcuts.js';
+export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
+export { setUpPage } from './dom/setup.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
+export {
+  MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite,
+} from './sites/sites.js';
+export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
 export {
   OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen,
 } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
 export { askText, checkText } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 
@@ -34,6 +42,7 @@ export { TOAST_MS, createToast } from './ui/toast.js';
  * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
  * @typedef {import('./ui/menu.js').MenuItem} MenuItem
  * @typedef {import('./ui/menu.js').MenuPlace} MenuPlace
+ * @typedef {import('./ui/site-list.js').SiteList} SiteList
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/sites/sites.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Sites, as people type them into a settings list ("example.com",
+ * "https://www.Example.com/shop") and as pages report them (`location.href`):
+ * the origin an extension asks Chrome for access to, the host a per-site
+ * on/off list keeps, whether a page is on a listed site (subdomains
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
+ *
+ * A site is a web host: http or https, with a dot in its name (or
+ * `localhost`). Text without a scheme is read as https.
+ *
+ * @module sites/sites
+ */
+/** The longest host name DNS allows, and so the longest site a list takes. */
+export declare const MAX_HOST_LENGTH = 253;
+/**
+ * The origin of a site: what Chrome grants access to, so `www.` and the
+ * scheme are kept (https unless typed otherwise); the port and path aren't.
+ *
+ * @param {unknown} input - What was typed or stored, or a page's address.
+ * @returns {string | null} The origin, or null when it isn't a web site.
+ * @example
+ * siteOrigin('example.com');              // 'https://example.com'
+ * siteOrigin('http://localhost:3000/x');  // 'http://localhost'
+ * siteOrigin('chrome://settings');        // null
+ */
+export declare function siteOrigin(input: unknown): string | null;
+/**
+ * The host a per-site list keeps: no scheme, port, path, leading `www.` or
+ * trailing dot, lower case. A list of hosts covers each one's subdomains
+ * ({@link onSite}, {@link hostPatterns}).
+ *
+ * @param {unknown} input - What was typed or stored, or a page's address.
+ * @returns {string | null} The host, or null when it isn't a web site.
+ * @example
+ * siteHost(' https://www.GitHub.com/a ');  // 'github.com'
+ * siteHost('news.bbc.co.uk');              // 'news.bbc.co.uk'
+ * siteHost('not a site');                  // null
+ */
+export declare function siteHost(input: unknown): string | null;
+/**
+ * Whether a host is one of the listed sites, or a subdomain of one
+ * ("docs.github.com" is on "github.com"; "notgithub.com" isn't).
+ *
+ * @param {string | null} host - From {@link siteHost} (null for a page that isn't a web site).
+ * @param {readonly string[]} sites - Hosts from {@link siteHost}.
+ * @returns {boolean} True when it's on one of them.
+ * @example
+ * onSite(siteHost(location.href), settings.neverSites);
+ */
+export declare function onSite(host: string | null, sites: readonly string[]): boolean;
+/**
+ * The match patterns for a listed host and its subdomains: to leave it out
+ * of a registered content script (`excludeMatches`).
+ *
+ * @param {string} host - From {@link siteHost}.
+ * @returns {string[]} Two match patterns.
+ * @example
+ * hostPatterns('example.com'); // ['*://example.com/*', '*://*.example.com/*']
+ */
+export declare function hostPatterns(host: string): string[];
+/**
+ * The host permission pattern for a site: its scheme and host, every path
+ * and port.
+ *
+ * @param {string} url - An origin from {@link siteOrigin}, or any web address.
+ * @returns {string} The pattern.
+ * @example
+ * originPattern('https://example.com');      // 'https://example.com/*'
+ * originPattern('https://bit.ly:8443/abc');  // 'https://bit.ly/*'
+ */
+export declare function originPattern(url: string): string;
+/**
+ * An origin as a settings list shows it: without `https://` (an http one
+ * keeps its scheme, so it reads as different).
+ *
+ * @param {string} site - An origin from {@link siteOrigin}, or a host.
+ * @returns {string} What to show.
+ * @example
+ * siteLabel('https://example.com'); // 'example.com'
+ * siteLabel('http://example.com');  // 'http://example.com'
+ */
+export declare function siteLabel(site: string): string;
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export declare function withSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export declare function withoutSite(sites: readonly string[], site: string): string[];
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export declare function withSiteReplaced(sites: readonly string[], site: string, edited: string): string[];

package/src/sites/sites.js

@@ -0,0 +1,169 @@
+/**
+ * Sites, as people type them into a settings list ("example.com",
+ * "https://www.Example.com/shop") and as pages report them (`location.href`):
+ * the origin an extension asks Chrome for access to, the host a per-site
+ * on/off list keeps, whether a page is on a listed site (subdomains
+ * included), the match patterns for both, and a list with a site added,
+ * taken out or edited. Pure.
+ *
+ * A site is a web host: http or https, with a dot in its name (or
+ * `localhost`). Text without a scheme is read as https.
+ *
+ * @module sites/sites
+ */
+
+/** The longest host name DNS allows, and so the longest site a list takes. */
+export const MAX_HOST_LENGTH = 253;
+
+/** A scheme at the start of what was typed; `localhost:8080` is a host and port, not one. */
+const SCHEME = /^[a-z][a-z\d+.-]*:(?!\d)/i;
+
+/**
+ * What was typed (or stored, or a page's address) as a web URL.
+ *
+ * @param {unknown} input - Anything.
+ * @returns {URL | null} The URL, or null when it isn't a web site's.
+ */
+function webUrl(input) {
+  // Only text: a stray number would otherwise read as an IP address (3 → "0.0.0.3").
+  const text = typeof input === 'string' ? input.trim() : '';
+  if (!text || /\s/.test(text)) return null;
+  try {
+    const url = new URL(SCHEME.test(text) ? text : `https://${text}`);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+    return url.hostname.includes('.') || url.hostname === 'localhost' ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The origin of a site: what Chrome grants access to, so `www.` and the
+ * scheme are kept (https unless typed otherwise); the port and path aren't.
+ *
+ * @param {unknown} input - What was typed or stored, or a page's address.
+ * @returns {string | null} The origin, or null when it isn't a web site.
+ * @example
+ * siteOrigin('example.com');              // 'https://example.com'
+ * siteOrigin('http://localhost:3000/x');  // 'http://localhost'
+ * siteOrigin('chrome://settings');        // null
+ */
+export function siteOrigin(input) {
+  const url = webUrl(input);
+  return url && `${url.protocol}//${url.hostname}`;
+}
+
+/**
+ * The host a per-site list keeps: no scheme, port, path, leading `www.` or
+ * trailing dot, lower case. A list of hosts covers each one's subdomains
+ * ({@link onSite}, {@link hostPatterns}).
+ *
+ * @param {unknown} input - What was typed or stored, or a page's address.
+ * @returns {string | null} The host, or null when it isn't a web site.
+ * @example
+ * siteHost(' https://www.GitHub.com/a ');  // 'github.com'
+ * siteHost('news.bbc.co.uk');              // 'news.bbc.co.uk'
+ * siteHost('not a site');                  // null
+ */
+export function siteHost(input) {
+  const url = webUrl(input);
+  if (!url) return null;
+  const host = url.hostname.replace(/^www\./, '').replace(/\.$/, '');
+  return (host.includes('.') || host === 'localhost') && host.length <= MAX_HOST_LENGTH ? host : null;
+}
+
+/**
+ * Whether a host is one of the listed sites, or a subdomain of one
+ * ("docs.github.com" is on "github.com"; "notgithub.com" isn't).
+ *
+ * @param {string | null} host - From {@link siteHost} (null for a page that isn't a web site).
+ * @param {readonly string[]} sites - Hosts from {@link siteHost}.
+ * @returns {boolean} True when it's on one of them.
+ * @example
+ * onSite(siteHost(location.href), settings.neverSites);
+ */
+export function onSite(host, sites) {
+  return host !== null && sites.some((site) => host === site || host.endsWith(`.${site}`));
+}
+
+/**
+ * The match patterns for a listed host and its subdomains: to leave it out
+ * of a registered content script (`excludeMatches`).
+ *
+ * @param {string} host - From {@link siteHost}.
+ * @returns {string[]} Two match patterns.
+ * @example
+ * hostPatterns('example.com'); // ['*://example.com/*', '*://*.example.com/*']
+ */
+export function hostPatterns(host) {
+  return [`*://${host}/*`, `*://*.${host}/*`];
+}
+
+/**
+ * The host permission pattern for a site: its scheme and host, every path
+ * and port.
+ *
+ * @param {string} url - An origin from {@link siteOrigin}, or any web address.
+ * @returns {string} The pattern.
+ * @example
+ * originPattern('https://example.com');      // 'https://example.com/*'
+ * originPattern('https://bit.ly:8443/abc');  // 'https://bit.ly/*'
+ */
+export function originPattern(url) {
+  const { protocol, hostname } = new URL(url);
+  return `${protocol}//${hostname}/*`;
+}
+
+/**
+ * An origin as a settings list shows it: without `https://` (an http one
+ * keeps its scheme, so it reads as different).
+ *
+ * @param {string} site - An origin from {@link siteOrigin}, or a host.
+ * @returns {string} What to show.
+ * @example
+ * siteLabel('https://example.com'); // 'example.com'
+ * siteLabel('http://example.com');  // 'http://example.com'
+ */
+export function siteLabel(site) {
+  return site.replace(/^https:\/\//, '');
+}
+
+/**
+ * A site list with `site` added: at the end, once (a site added again moves
+ * there).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to add.
+ * @returns {string[]} A new list.
+ * @example
+ * withSite(['a.com', 'b.com'], 'a.com'); // ['b.com', 'a.com']
+ */
+export function withSite(sites, site) {
+  return [...withoutSite(sites, site), site];
+}
+
+/**
+ * A site list without `site`.
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site to take out.
+ * @returns {string[]} A new list.
+ */
+export function withoutSite(sites, site) {
+  return sites.filter((s) => s !== site);
+}
+
+/**
+ * A site list with `site` edited to `edited`, in its place, once (an edit
+ * to a site already listed merges the two).
+ *
+ * @param {readonly string[]} sites - The list.
+ * @param {string} site - The site as it was.
+ * @param {string} edited - What it was edited to.
+ * @returns {string[]} A new list.
+ * @example
+ * withSiteReplaced(['a.com', 'b.com'], 'a.com', 'b.com'); // ['b.com']
+ */
+export function withSiteReplaced(sites, site, edited) {
+  return [...new Set(sites.map((s) => (s === site ? edited : s)))];
+}

package/src/styles/chrome-ui.css

@@ -621,6 +621,9 @@ label.row, .row[actionable] { cursor: pointer; }
 .list { list-style: none; margin: 0; padding: 0; }
 .list:empty { display: none; }
 
+/* A row that adds to the list above it (createSiteList): a field the row's width, then "Add". */
+.row.add input { flex: 1; min-width: 0; }
+
 /* About card, as chrome://settings/help (about_page.css): a 32px logo 10px from a 20px title. */
 .about-product { justify-content: flex-start; gap: 10px; }
 .product-title { font-size: 20px; }
@@ -780,11 +783,11 @@ label.row, .row[actionable] { cursor: pointer; }
 
 /* ------------------------------------------------------- Toast (cr-toast) */
 
+/* A manual popover (createToast), in the top layer, or a page's own element shown and hidden with
+   `hidden`: the popover defaults undone either way. */
 .toast {
     position: fixed;
-    left: 0;
-    bottom: 0;
-    z-index: 2;
+    inset: auto auto 0 0;
     display: flex;
     align-items: center;
     gap: 32px;
@@ -796,10 +799,16 @@ label.row, .row[actionable] { cursor: pointer; }
     border-radius: 8px;
     background: var(--toast-bg);
     color: var(--toast-text);
+    width: auto;
+    height: auto;
+    overflow: visible;
+    border: 0;
     line-height: 20px;
     box-shadow: 0 2px 4px 0 rgb(0 0 0 / 0.28);
 }
 
+.toast[popover]:not(:popover-open) { display: none; }
+
 .toast button {
     height: auto;
     margin-right: -8px;
@@ -1082,9 +1091,7 @@ button.floating .icon { width: 20px; height: 20px; }
 
 /* The toast in a panel: the panel's width less 8px each side, above the footer. */
 .side-panel .toast {
-    left: 8px;
-    right: 8px;
-    bottom: 56px;
+    inset: auto 8px 56px 8px;
     min-width: 0;
     max-width: none;
     margin: 0;

package/src/testing/browser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A browser that passes for a person's: for live checks against real sites,
+ * many of which turn away a browser that says it's automated (a
+ * "HeadlessChrome" user agent, `navigator.webdriver`), or show it something
+ * else. And closing every browser a run started when it's stopped (Ctrl-C,
+ * a kill), so nothing is left running.
+ *
+ * @module testing/browser
+ */
+import type { Browser } from 'playwright';
+/**
+ * Launch options (for `chromium.launch`, `launchExtension` or
+ * `extensionProfile`) for a browser that doesn't announce it's automated:
+ * Blink's automation tells off, and without Playwright's
+ * `--enable-automation` (the "controlled by automated test software" bar).
+ * Pair it with {@link chromeUserAgent} for the user agent.
+ *
+ * @template {{args?: string[], ignoreDefaultArgs?: boolean | string[]} & Record<string, unknown>} O
+ * @param {O} [options] - Other launch options (`proxy`, `userAgent`, `locale`, …), kept.
+ * @returns {Omit<O, 'args' | 'ignoreDefaultArgs'> & {args: string[], ignoreDefaultArgs: string[]}} The
+ *   options, with the switches added.
+ * @example
+ * const plain = await chromium.launch(realisticBrowser({ proxy }));
+ * const launched = await launchExtension(chromium, build, realisticBrowser({ userAgent: await chromeUserAgent(plain) }));
+ */
+export declare function realisticBrowser<O extends {
+    args?: string[];
+    ignoreDefaultArgs?: boolean | string[];
+} & Record<string, unknown>>(options?: O): Omit<O, 'args' | 'ignoreDefaultArgs'> & {
+    args: string[];
+    ignoreDefaultArgs: string[];
+};
+/**
+ * The browser's user agent as ordinary Chrome's: "HeadlessChrome" (what
+ * headless mode sends) made "Chrome", the version kept.
+ *
+ * @param {Browser} browser - A launched Chromium.
+ * @returns {Promise<string>} The user agent to give its contexts (`userAgent`).
+ */
+export declare function chromeUserAgent(browser: Browser): Promise<string>;
+/**
+ * On Ctrl-C or a kill, run `close` (given `ms` at most) and exit, so the
+ * browsers a run started don't outlive it.
+ *
+ * @param {() => Promise<unknown>} close - Closes everything (`Promise.allSettled` of each close, say).
+ * @param {number} [ms] - How long `close` may take. Default 10 s.
+ * @returns {() => void} Takes the handlers off again (call it once the run has closed everything itself).
+ * @example
+ * const stop = closeOnSignal(() => Promise.allSettled([plain.close(), launched.close()]));
+ * try { … } finally { stop(); await plain.close(); await launched.close(); }
+ */
+export declare function closeOnSignal(close: () => Promise<unknown>, ms?: number): () => void;

package/src/testing/browser.js

@@ -0,0 +1,79 @@
+/**
+ * A browser that passes for a person's: for live checks against real sites,
+ * many of which turn away a browser that says it's automated (a
+ * "HeadlessChrome" user agent, `navigator.webdriver`), or show it something
+ * else. And closing every browser a run started when it's stopped (Ctrl-C,
+ * a kill), so nothing is left running.
+ *
+ * @module testing/browser
+ */
+
+import { within } from '../time/time.js';
+
+/** @import { Browser } from 'playwright' */
+
+/** The switch that hides `navigator.webdriver` and Blink's other automation tells. */
+const NOT_AUTOMATED = '--disable-blink-features=AutomationControlled';
+
+/**
+ * Launch options (for `chromium.launch`, `launchExtension` or
+ * `extensionProfile`) for a browser that doesn't announce it's automated:
+ * Blink's automation tells off, and without Playwright's
+ * `--enable-automation` (the "controlled by automated test software" bar).
+ * Pair it with {@link chromeUserAgent} for the user agent.
+ *
+ * @template {{args?: string[], ignoreDefaultArgs?: boolean | string[]} & Record<string, unknown>} O
+ * @param {O} [options] - Other launch options (`proxy`, `userAgent`, `locale`, …), kept.
+ * @returns {Omit<O, 'args' | 'ignoreDefaultArgs'> & {args: string[], ignoreDefaultArgs: string[]}} The
+ *   options, with the switches added.
+ * @example
+ * const plain = await chromium.launch(realisticBrowser({ proxy }));
+ * const launched = await launchExtension(chromium, build, realisticBrowser({ userAgent: await chromeUserAgent(plain) }));
+ */
+export function realisticBrowser(options) {
+  const { args = [], ignoreDefaultArgs, ...rest } = options ?? /** @type {O} */ ({});
+  const ignored = Array.isArray(ignoreDefaultArgs) ? ignoreDefaultArgs : [];
+  return { ...rest, args: [...args, NOT_AUTOMATED], ignoreDefaultArgs: [...ignored, '--enable-automation'] };
+}
+
+/**
+ * The browser's user agent as ordinary Chrome's: "HeadlessChrome" (what
+ * headless mode sends) made "Chrome", the version kept.
+ *
+ * @param {Browser} browser - A launched Chromium.
+ * @returns {Promise<string>} The user agent to give its contexts (`userAgent`).
+ */
+export async function chromeUserAgent(browser) {
+  const context = await browser.newContext();
+  try {
+    const page = await context.newPage();
+    return (await page.evaluate(() => navigator.userAgent)).replace('HeadlessChrome', 'Chrome');
+  } finally {
+    await context.close();
+  }
+}
+
+/** The signals a run is stopped with, and their exit codes (128 + the signal's number). */
+const SIGNALS = /** @type {const} */ ([['SIGINT', 130], ['SIGTERM', 143]]);
+
+/**
+ * On Ctrl-C or a kill, run `close` (given `ms` at most) and exit, so the
+ * browsers a run started don't outlive it.
+ *
+ * @param {() => Promise<unknown>} close - Closes everything (`Promise.allSettled` of each close, say).
+ * @param {number} [ms] - How long `close` may take. Default 10 s.
+ * @returns {() => void} Takes the handlers off again (call it once the run has closed everything itself).
+ * @example
+ * const stop = closeOnSignal(() => Promise.allSettled([plain.close(), launched.close()]));
+ * try { … } finally { stop(); await plain.close(); await launched.close(); }
+ */
+export function closeOnSignal(close, ms = 10_000) {
+  /** @type {[string, () => void][]} */
+  const handlers = SIGNALS.map(([signal, code]) => [signal, () => {
+    within(Promise.resolve().then(close), ms, undefined).finally(() => process.exit(code));
+  }]);
+  for (const [signal, handler] of handlers) process.once(signal, handler);
+  return () => {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  };
+}

package/src/testing/e2e.d.ts

@@ -143,11 +143,16 @@ export declare function offscreenEmulator(cdp: CDPSession, suffix?: string): Pro
  * @returns {Promise<() => Promise<unknown[]>>} Reads the recorded `path`s, oldest first.
  */
 export declare function recordIconCalls(worker: Worker): Promise<() => Promise<unknown[]>>;
+/** How long one check may take before it's failed, in ms: long enough for a slow real-browser check, short of a hang. */
+export declare const CHECK_MS = 60000;
 export type CheckRunner = {
     /**
-     * Run one check; resolves to whether it passed.
+     *   Run one check, failed if it takes longer than `timeout` (default the runner's); resolves to
+     *   whether it passed.
      */
-    check: (name: string, fn: () => unknown) => Promise<boolean>;
+    check: (name: string, fn: () => unknown, options?: {
+        timeout?: number;
+    }) => Promise<boolean>;
     /**
      * Count a failure found outside any check (a page's
      * uncaught error, say): printed now, listed and counted at the end.
@@ -163,23 +168,31 @@ export type CheckRunner = {
  * script goes on, so one run shows everything that's wrong.
  *
  * @typedef {object} CheckRunner
- * @property {(name: string, fn: () => unknown) => Promise<boolean>} check Run one check; resolves to whether it passed.
+ * @property {(name: string, fn: () => unknown, options?: {timeout?: number}) => Promise<boolean>} check
+ *   Run one check, failed if it takes longer than `timeout` (default the runner's); resolves to
+ *   whether it passed.
  * @property {(name: string) => void} fail Count a failure found outside any check (a page's
  *   uncaught error, say): printed now, listed and counted at the end.
  * @property {() => void} finish Print the tally, and exit with 1 if anything failed.
  */
 /**
  * Make a {@link CheckRunner}: "✓ name" for a pass, "✗ name" and the error's
- * message, indented, for a failure.
+ * message, indented, for a failure. A check that hangs (a page that never
+ * answers) fails once its time is up, and the script goes on; what it was
+ * doing isn't stopped, so `finish()` exits rather than wait for it.
  *
+ * @param {{timeout?: number}} [options] - `timeout`: each check's limit in ms. Default {@link CHECK_MS}.
  * @returns {CheckRunner} The runner.
  * @example
  * const { check, fail, finish } = checkRunner();
  * page.on('pageerror', (error) => fail(`page error: ${error.message}`));
  * await check('the menu opens', async () => { … });
+ * await check('a live site answers', async () => { … }, { timeout: 120_000 });
  * finish();
  */
-export declare function checkRunner(): CheckRunner;
+export declare function checkRunner({ timeout: runnerTimeout }?: {
+    timeout?: number;
+}): CheckRunner;
 export type SchemePage = {
     /**
      * From the extension's root, e.g. `options/options.html`.

package/src/testing/e2e.js

@@ -12,6 +12,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { deadline } from '../time/time.js';
 
 /** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
 
@@ -181,12 +182,17 @@ export async function recordIconCalls(worker) {
   return () => worker.evaluate(() => /** @type {{iconCalls: unknown[]}} */ (/** @type {unknown} */ (globalThis)).iconCalls);
 }
 
+/** How long one check may take before it's failed, in ms: long enough for a slow real-browser check, short of a hang. */
+export const CHECK_MS = 60_000;
+
 /**
  * A runner for a script of named checks: each failure is reported and the
  * script goes on, so one run shows everything that's wrong.
  *
  * @typedef {object} CheckRunner
- * @property {(name: string, fn: () => unknown) => Promise<boolean>} check Run one check; resolves to whether it passed.
+ * @property {(name: string, fn: () => unknown, options?: {timeout?: number}) => Promise<boolean>} check
+ *   Run one check, failed if it takes longer than `timeout` (default the runner's); resolves to
+ *   whether it passed.
  * @property {(name: string) => void} fail Count a failure found outside any check (a page's
  *   uncaught error, say): printed now, listed and counted at the end.
  * @property {() => void} finish Print the tally, and exit with 1 if anything failed.
@@ -194,23 +200,29 @@ export async function recordIconCalls(worker) {
 
 /**
  * Make a {@link CheckRunner}: "✓ name" for a pass, "✗ name" and the error's
- * message, indented, for a failure.
+ * message, indented, for a failure. A check that hangs (a page that never
+ * answers) fails once its time is up, and the script goes on; what it was
+ * doing isn't stopped, so `finish()` exits rather than wait for it.
  *
+ * @param {{timeout?: number}} [options] - `timeout`: each check's limit in ms. Default {@link CHECK_MS}.
  * @returns {CheckRunner} The runner.
  * @example
  * const { check, fail, finish } = checkRunner();
  * page.on('pageerror', (error) => fail(`page error: ${error.message}`));
  * await check('the menu opens', async () => { … });
+ * await check('a live site answers', async () => { … }, { timeout: 120_000 });
  * finish();
  */
-export function checkRunner() {
+export function checkRunner({ timeout: runnerTimeout = CHECK_MS } = {}) {
   /** @type {string[]} */
   const failures = [];
   let passed = 0;
   return {
-    async check(name, fn) {
+    async check(name, fn, { timeout = runnerTimeout } = {}) {
       try {
-        await fn();
+        await deadline(Promise.resolve().then(fn), timeout, (_, reject) => {
+          reject(new Error(`Timed out after ${timeout / 1000} s`));
+        });
         passed++;
         console.log(`  ✓ ${name}`);
         return true;

package/src/testing/index.d.ts

@@ -1,11 +1,15 @@
 /**
  * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
- * end-to-end tests and a server for their pages, Chrome's install warnings
- * and saved tab groups, and checks for a packaging test. Node only.
+ * end-to-end tests (time limits, a pool, a browser that passes for a
+ * person's) and a server for their pages, Chrome's install warnings and
+ * saved tab groups, and checks for a packaging test. Node only.
  *
  * @module testing
  */
-export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
+export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
+export { eachLimited } from './pool.js';
 export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';