@arraypress/extension-kit 1.9.0 → 1.11.0

package/src/testing/index.d.ts

@@ -8,16 +8,18 @@
  */
 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, runChecks, until, } from './e2e.js';
+export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, stopWorker, until, } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { REPORT_MARKER, liveUsage, reportFolder, runLiveCheck } from './live-run.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
 export { heartbeat } from './heartbeat.js';
 export { playPermissionPrompt } from './prompt.js';
+export { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { LOCAL_QUOTA_BYTES, SYNC_MAX_ITEMS, SYNC_QUOTA_BYTES, SYNC_WRITES_PER_HOUR, SYNC_WRITES_PER_MINUTE, fakeChromeStorage, } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
@@ -28,8 +30,10 @@ export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
 export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
 export type LaunchOptions = import('./e2e.js').LaunchOptions;
 export type Messages = import('./messages.js').Messages;
+export type CdpNode = import('./pages.js').CdpNode;
 export type Exit = import('./live.js').Exit;
 export type LiveOptions = import('./live.js').LiveOptions;
+export type LiveSite = import('./live-run.js').LiveSite;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
 export type Manifest = import('./warnings.js').Manifest;
 export type Reply = import('./server.js').Reply;
@@ -45,8 +49,10 @@ export type TestServer = import('./server.js').TestServer;
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
  * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./pages.js').CdpNode} CdpNode
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
+ * @typedef {import('./live-run.js').LiveSite} LiveSite
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/index.js

@@ -10,17 +10,21 @@
 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, runChecks, until,
+  CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, runChecks, stopWorker, until,
 } from './e2e.js';
 export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { REPORT_MARKER, liveUsage, reportFolder, runLiveCheck } from './live-run.js';
 export { eachLimited } from '../time/pool.js';
 export { filesIn, launchDownloading } from './downloads.js';
 export { fakeLanguageModel } from './fake-model.js';
 export { messageLookup, readMessages } from './messages.js';
 export { heartbeat } from './heartbeat.js';
 export { playPermissionPrompt } from './prompt.js';
+export { callTabModule, nodeAttribute, nodeText, pierceNodes, tabIdOf } from './pages.js';
 export { serve, testCertificate } from './server.js';
-export { SYNC_QUOTA_BYTES, SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export {
+  LOCAL_QUOTA_BYTES, SYNC_MAX_ITEMS, SYNC_QUOTA_BYTES, SYNC_WRITES_PER_HOUR, SYNC_WRITES_PER_MINUTE, fakeChromeStorage,
+} from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
 export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
@@ -35,8 +39,10 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
  * @typedef {import('./messages.js').Messages} Messages
+ * @typedef {import('./pages.js').CdpNode} CdpNode
  * @typedef {import('./live.js').Exit} Exit
  * @typedef {import('./live.js').LiveOptions} LiveOptions
+ * @typedef {import('./live-run.js').LiveSite} LiveSite
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/live-run.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { exitPoint } from './live.js';
+import type { BrowserType, Page } from 'playwright';
+import type { LaunchedExtension } from './e2e.js';
+import type { Exit } from './live.js';
+export type LiveSite = {
+    name: string;
+    url: string;
+    category: string;
+};
+export type LiveRun<S extends LiveSite, R> = {
+    /**
+     * The report's folder (made empty).
+     */
+    dir: string;
+    /**
+     * When it started (ISO).
+     */
+    started: string;
+    /**
+     * When it finished (ISO).
+     */
+    finished: string;
+    /**
+     * Where the traffic left.
+     */
+    exit: Exit | null;
+    /**
+     * How the browsers looked.
+     */
+    browser: {
+        locale: string;
+        timezone: string;
+        proxy: string;
+    };
+    /**
+     * Each site's visit, in the sites' order.
+     */
+    results: {
+        site: S;
+        visit: R;
+    }[];
+};
+/** @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 declare const liveUsage: (categories: string[], concurrency: number) => string;
+/** The file that marks a folder as a live report the kit made, so the next run may replace it. */
+export declare const REPORT_MARKER = ".live-report";
+/**
+ * The folder a run's report goes in, made empty. Only a folder the kit made is ever emptied:
+ * the checker's own (`own`), or one carrying {@link REPORT_MARKER} from an earlier run. A new
+ * or empty folder is taken (and marked); a folder with anything else in it is refused, so
+ * `--out .` or `--out ~/Desktop` can't delete what's there.
+ *
+ * @param {string} dir - The folder.
+ * @param {{own?: boolean}} [options] - `own`: the checker's default folder, replaced without asking.
+ * @returns {Promise<string>} `dir`, empty but for the marker.
+ * @throws {Error} When the folder holds files and isn't a report folder.
+ *
+ * @example
+ * await reportFolder('/tmp/report'); // made, or emptied if an earlier run made it
+ */
+export declare function reportFolder(dir: string, { own }?: {
+    own?: boolean;
+}): Promise<string>;
+/**
+ * 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 or `--out` names a folder with other files in it ({@link reportFolder}). A visit
+ * that throws, runs out of time or loses its browser is `failed` with why, and the run goes on
+ * (the slot gets a new browser).
+ *
+ * @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'`, or the error's message.
+ * @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 declare function runLiveCheck<S extends LiveSite, R>({ chromium, build, prefix, root, sites, categories, pageMs, visit, failed, onResult, command }: {
+    chromium: BrowserType;
+    build: string;
+    prefix: string;
+    root: string;
+    sites: S[];
+    categories: string[];
+    pageMs: number;
+    visit: (browser: LaunchedExtension, page: Page, site: S) => Promise<R>;
+    failed: (site: S, error: string) => R;
+    onResult?: (result: {
+        site: S;
+        visit: R;
+    }) => void;
+    command?: {
+        argv?: string[];
+        env?: Record<string, string | undefined>;
+        concurrency?: number;
+        findExit?: typeof exitPoint;
+    };
+}): Promise<LiveRun<S, R>>;

package/src/testing/live-run.js

@@ -0,0 +1,206 @@
+/**
+ * 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, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { deadline, 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`;
+
+/** The file that marks a folder as a live report the kit made, so the next run may replace it. */
+export const REPORT_MARKER = '.live-report';
+
+/**
+ * The folder a run's report goes in, made empty. Only a folder the kit made is ever emptied:
+ * the checker's own (`own`), or one carrying {@link REPORT_MARKER} from an earlier run. A new
+ * or empty folder is taken (and marked); a folder with anything else in it is refused, so
+ * `--out .` or `--out ~/Desktop` can't delete what's there.
+ *
+ * @param {string} dir - The folder.
+ * @param {{own?: boolean}} [options] - `own`: the checker's default folder, replaced without asking.
+ * @returns {Promise<string>} `dir`, empty but for the marker.
+ * @throws {Error} When the folder holds files and isn't a report folder.
+ *
+ * @example
+ * await reportFolder('/tmp/report'); // made, or emptied if an earlier run made it
+ */
+export async function reportFolder(dir, { own = false } = {}) {
+  const entries = await readdir(dir).catch(() => /** @type {string[]} */ ([]));
+  if (entries.length && !own && !entries.includes(REPORT_MARKER)) {
+    throw new Error(`${dir} has files in it and isn't a report folder: choose a new or empty folder for --out`);
+  }
+  if (entries.length) await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, REPORT_MARKER), 'A live check\'s report: the next run replaces this folder.\n');
+  return dir;
+}
+
+/** Stands for a visit that ran out of time. */
+const LATE = Symbol('late');
+
+/**
+ * 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 or `--out` names a folder with other files in it ({@link reportFolder}). A visit
+ * that throws, runs out of time or loses its browser is `failed` with why, and the run goes on
+ * (the slot gets a new browser).
+ *
+ * @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'`, or the error's message.
+ * @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);
+  }
+  /** @type {string} */
+  let dir;
+  try {
+    dir = await reportFolder(options.out ? path.resolve(options.out) : path.join(root, 'test', 'live', 'report'), { own: !options.out });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(2);
+  }
+
+  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) => {
+      /** @type {R} */
+      let outcome;
+      try {
+        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();
+        try {
+          const result = await deadline(/** @type {Promise<R | typeof LATE>} */ (visit(launched, page, site)), pageMs, (resolve) => resolve(LATE));
+          if (result === LATE) throw new Error('timed out');
+          outcome = result;
+        } finally {
+          await within(page.close(), 15_000, undefined);
+        }
+      } catch (error) {
+        // A visit that failed may have left its browser stuck, or lost it: the slot gets a new one.
+        await within(Promise.resolve(browsers[slot]?.close()), 15_000, undefined);
+        browsers[slot] = null;
+        outcome = failed(site, error instanceof Error ? error.message : String(error));
+      }
+      results[index] = { site, visit: outcome };
+      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/messages.d.ts

@@ -21,13 +21,17 @@ export type Messages = Record<string, {
  */
 export declare function readMessages(extensionDir: string, locale: string): Messages;
 /**
- * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ * `chrome.i18n.getMessage` over a locale's real messages, as Chrome reads them (checked against
+ * Chromium): names found whatever their case, named placeholders and `$1`–`$9` filled, `$$` a
+ * dollar sign, '' for a missing key, `undefined` for more than nine substitutions.
  *
  * @param {string} extensionDir - The extension's folder.
  * @param {string} [locale] - Default "en"; another locale is read over en.
- * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @returns {(key: string, substitutions?: string | number | (string | number)[]) => string} The lookup.
+ * @throws {Error} When a message names a placeholder it doesn't define (Chrome refuses to load the extension).
+ *
  * @example
  * const t = messageLookup('extension');
  * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
  */
-export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | string[]) => string;
+export declare function messageLookup(extensionDir: string, locale?: string): (key: string, substitutions?: string | number | (string | number)[]) => string;

package/src/testing/messages.js

@@ -2,7 +2,8 @@
  * Chrome's message lookup for an extension's unit tests: its real `_locales`
  * files, a locale's messages over `en`'s, named placeholders ("$SITE$" →
  * `{site: {content: '$1'}}`) filled from substitutions as
- * `chrome.i18n.getMessage` fills them. Node only. From the copies in Better
+ * `chrome.i18n.getMessage` fills them, and refused as Chrome refuses them (a
+ * placeholder that isn't defined). Node only. From the copies in Better
  * Prices, Better Downloads, Better Saves and Clean Links (`test/helpers/i18n.js`).
  *
  * @module testing/messages
@@ -29,23 +30,63 @@ export function readMessages(extensionDir, locale) {
   return JSON.parse(readFileSync(path.join(extensionDir, '_locales', locale, 'messages.json'), 'utf8'));
 }
 
+/** A named placeholder in a message, as Chrome reads one: `$SITE$` (letters, digits, `_`, `@`). */
+const PLACEHOLDER = /\$([A-Za-z0-9_@]+)\$/g;
+
+/**
+ * A message with its named placeholders put in, as Chrome does when it loads an extension.
+ *
+ * @param {string} key - The message's name, for the error.
+ * @param {Messages[string]} entry - The message.
+ * @returns {string} The message, `$1`-style substitutions still to fill.
+ * @throws {Error} When it names a placeholder it doesn't define: Chrome refuses to load such an extension.
+ */
+function withPlaceholders(key, entry) {
+  const contents = new Map(Object.entries(entry.placeholders ?? {}).map(([name, { content }]) => [name.toLowerCase(), content]));
+  return entry.message.replace(PLACEHOLDER, (_, name) => {
+    const content = contents.get(name.toLowerCase());
+    if (content === undefined) throw new Error(`Message “${key}” uses $${name}$ but has no such placeholder: Chrome wouldn't load the extension`);
+    return content;
+  });
+}
+
 /**
- * `chrome.i18n.getMessage` over a locale's real messages ('' for a missing key, as Chrome gives).
+ * Fill a message's substitutions as Chrome does: `$1`–`$9` from the list ('' past its end), `$$`
+ * a dollar sign; a `$` before anything else is dropped with what follows it.
+ *
+ * @param {string} message - The message, named placeholders already put in.
+ * @param {readonly string[]} subs - The substitutions.
+ * @returns {string} The text.
+ */
+function substituted(message, subs) {
+  return message.replace(/\$(\$+|[\s\S])?/g, (_, next) => {
+    if (next === undefined) return '';
+    if (next.startsWith('$')) return next;
+    return /[1-9]/.test(next) ? String(subs[Number(next) - 1] ?? '') : '';
+  });
+}
+
+/**
+ * `chrome.i18n.getMessage` over a locale's real messages, as Chrome reads them (checked against
+ * Chromium): names found whatever their case, named placeholders and `$1`–`$9` filled, `$$` a
+ * dollar sign, '' for a missing key, `undefined` for more than nine substitutions.
  *
  * @param {string} extensionDir - The extension's folder.
  * @param {string} [locale] - Default "en"; another locale is read over en.
- * @returns {(key: string, substitutions?: string | string[]) => string} The lookup.
+ * @returns {(key: string, substitutions?: string | number | (string | number)[]) => string} The lookup.
+ * @throws {Error} When a message names a placeholder it doesn't define (Chrome refuses to load the extension).
+ *
  * @example
  * const t = messageLookup('extension');
  * t('optionsMoreActions', ['example.com']); // 'More actions for example.com'
  */
 export function messageLookup(extensionDir, locale = 'en') {
-  const messages = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  const read = { ...readMessages(extensionDir, 'en'), ...(locale === 'en' ? {} : readMessages(extensionDir, locale)) };
+  const messages = new Map(Object.entries(read).map(([key, entry]) => [key.toLowerCase(), withPlaceholders(key, entry)]));
   return (key, substitutions = []) => {
-    const entry = messages[key];
-    if (!entry) return '';
-    const subs = [substitutions].flat();
-    return entry.message.replace(/\$([A-Za-z_]+)\$/g, (_, name) => (entry.placeholders?.[name.toLowerCase()]?.content ?? '')
-      .replace(/\$(\d)/g, (/** @type {string} */ __, /** @type {string} */ n) => subs[Number(n) - 1] ?? ''));
+    const subs = [substitutions].flat().map(String);
+    if (subs.length > 9) return /** @type {string} */ (/** @type {unknown} */ (undefined));
+    const message = messages.get(key.toLowerCase());
+    return message === undefined ? '' : substituted(message, subs);
   };
 }

package/src/testing/package.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helpers for an extension's packaging test: list the folder, list the real
  * zip of it, and find every path the extension names that doesn't resolve to
- * a file inside it (a broken import, a stylesheet link, a manifest entry).
+ * a file the zip holds (a broken import, a stylesheet link, a manifest entry).
  *
  * @module testing/package
  */
@@ -33,6 +33,10 @@ export type ManifestFiles = {
     options_ui?: {
         page?: string;
     };
+    /**
+     * The options page, the older way.
+     */
+    options_page?: string;
     /**
      * The popup and toolbar icon.
      */
@@ -56,6 +60,39 @@ export type ManifestFiles = {
     web_accessible_resources?: {
         resources: string[];
     }[];
+    /**
+     * Scripts and styles Chrome puts in pages.
+     */
+    content_scripts?: {
+        js?: string[];
+        css?: string[];
+    }[];
+    /**
+     * The locale whose `_locales/<locale>/messages.json` must be there.
+     */
+    default_locale?: string;
+    /**
+     * Rule files.
+     */
+    declarative_net_request?: {
+        rule_resources?: {
+            path: string;
+        }[];
+    };
+    /**
+     * Pages that replace Chrome's (the new tab page).
+     */
+    chrome_url_overrides?: Record<string, string>;
+    /**
+     * The DevTools page.
+     */
+    devtools_page?: string;
+    /**
+     * Sandboxed pages.
+     */
+    sandbox?: {
+        pages?: string[];
+    };
 };
 /**
  * The parts of a manifest that name files.
@@ -63,16 +100,25 @@ export type ManifestFiles = {
  * @typedef {object} ManifestFiles
  * @property {{service_worker?: string}} [background] The worker.
  * @property {{page?: string}} [options_ui] The options page.
+ * @property {string} [options_page] The options page, the older way.
  * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
  * @property {{default_path?: string}} [side_panel] The side panel.
  * @property {Record<string, string>} [icons] The extension's icons.
  * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ * @property {{js?: string[], css?: string[]}[]} [content_scripts] Scripts and styles Chrome puts in pages.
+ * @property {string} [default_locale] The locale whose `_locales/<locale>/messages.json` must be there.
+ * @property {{rule_resources?: {path: string}[]}} [declarative_net_request] Rule files.
+ * @property {Record<string, string>} [chrome_url_overrides] Pages that replace Chrome's (the new tab page).
+ * @property {string} [devtools_page] The DevTools page.
+ * @property {{pages?: string[]}} [sandbox] Sandboxed pages.
  */
 /**
  * The paths a manifest names, from the extension's root.
  *
  * @param {ManifestFiles} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ * @returns {string[]} Worker, pages, icons, side panel, content scripts and their styles, the default
+ *   locale's messages, rule files, overridden and DevTools pages, and web-accessible resources
+ *   (less patterns with `*`).
  */
 export declare function manifestReferences(manifest: ManifestFiles): string[];
 /**
@@ -84,11 +130,14 @@ export declare function manifestReferences(manifest: ManifestFiles): string[];
  */
 export declare function referencedPath(reference: string): string;
 /**
- * Every path the extension names that isn't a file inside it: relative
- * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
- * or `?query` is ignored: `getURL('options.html#workspaces')` names
- * `options.html`.
+ * Every path the extension names that isn't a file it ships: relative imports in its scripts
+ * (`from`, `import()` and a bare `import './x.js'`), `chrome.runtime.getURL('…')` paths,
+ * `src`/`href` in its pages, `url(…)` and `@import` in its stylesheets, the manifest's entries
+ * ({@link manifestReferences}), and any `extra` paths. A file that's there but left out of the
+ * zip (`shipsFile`: an SVG under `icons/`, a declaration, a vendor stamp) is as missing as one
+ * that isn't: the store build won't have it. A `#fragment` or `?query` is ignored:
+ * `getURL('options.html#workspaces')` names `options.html`. A path starting `/` is from the
+ * extension's root. Files that don't ship aren't read.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).