@arraypress/extension-kit 1.0.0 → 1.2.0

package/src/testing/package.d.ts

@@ -20,17 +20,75 @@ export declare function filesUnder(dir: string): Promise<string[]>;
  * @returns {Promise<string[]>} Entry names, sorted.
  */
 export declare function zipEntries(from: string, exclude?: readonly string[]): Promise<string[]>;
+export type ManifestFiles = {
+    /**
+     * The worker.
+     */
+    background?: {
+        service_worker?: string;
+    };
+    /**
+     * The options page.
+     */
+    options_ui?: {
+        page?: string;
+    };
+    /**
+     * The popup and toolbar icon.
+     */
+    action?: {
+        default_popup?: string;
+        default_icon?: string | Record<string, string>;
+    };
+    /**
+     * The side panel.
+     */
+    side_panel?: {
+        default_path?: string;
+    };
+    /**
+     * The extension's icons.
+     */
+    icons?: Record<string, string>;
+    /**
+     * Files pages may load.
+     */
+    web_accessible_resources?: {
+        resources: string[];
+    }[];
+};
+/**
+ * The parts of a manifest that name files.
+ *
+ * @typedef {object} ManifestFiles
+ * @property {{service_worker?: string}} [background] The worker.
+ * @property {{page?: string}} [options_ui] The options page.
+ * @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.
+ */
 /**
  * The paths a manifest names, from the extension's root.
  *
- * @param {Record<string, any>} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ * @param {ManifestFiles} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ */
+export declare function manifestReferences(manifest: ManifestFiles): string[];
+/**
+ * The file a reference names: the path without its `#fragment` or `?query`
+ * (`options.html#workspaces` is `options.html`). Pure.
+ *
+ * @param {string} reference - A path as the extension writes it.
+ * @returns {string} The path alone; '' for a reference to the page itself (`#top`).
  */
-export declare function manifestReferences(manifest: Record<string, any>): 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.
+ * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
+ * or `?query` is ignored: `getURL('options.html#workspaces')` names
+ * `options.html`.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).

package/src/testing/package.js

@@ -43,28 +43,57 @@ export async function zipEntries(from, exclude) {
   }
 }
 
+/**
+ * The parts of a manifest that name files.
+ *
+ * @typedef {object} ManifestFiles
+ * @property {{service_worker?: string}} [background] The worker.
+ * @property {{page?: string}} [options_ui] The options page.
+ * @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.
+ */
+
 /**
  * The paths a manifest names, from the extension's root.
  *
- * @param {Record<string, any>} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ * @param {ManifestFiles} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
  */
 export function manifestReferences(manifest) {
+  const icon = manifest.action?.default_icon;
   return [
     manifest.background?.service_worker,
     manifest.options_ui?.page,
     manifest.action?.default_popup,
     manifest.side_panel?.default_path,
     ...Object.values(manifest.icons ?? {}),
-    ...Object.values(manifest.action?.default_icon ?? {}),
-    ...(manifest.web_accessible_resources ?? []).flatMap((/** @type {{resources: string[]}} */ entry) => entry.resources),
-  ].filter((ref) => typeof ref === 'string' && !ref.includes('*'));
+    ...(typeof icon === 'string' ? [icon] : Object.values(icon ?? {})),
+    ...(manifest.web_accessible_resources ?? []).flatMap((entry) => entry.resources),
+  ].filter((ref) => typeof ref === 'string').filter((ref) => !ref.includes('*'));
+}
+
+/**
+ * The file a reference names: the path without its `#fragment` or `?query`
+ * (`options.html#workspaces` is `options.html`). Pure.
+ *
+ * @param {string} reference - A path as the extension writes it.
+ * @returns {string} The path alone; '' for a reference to the page itself (`#top`).
+ */
+export function referencedPath(reference) {
+  return reference.replace(/[?#].*$/s, '');
 }
 
+/** A reference with a scheme (`https:`, `data:`, `mailto:`) or protocol-relative: not a file of the extension. */
+const ELSEWHERE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+
 /**
  * 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.
+ * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
+ * or `?query` is ignored: `getURL('options.html#workspaces')` names
+ * `options.html`.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
@@ -76,7 +105,9 @@ export async function missingReferences(dir, extra = []) {
   const missing = [];
   /** @param {string} from @param {string} target */
   const check = (from, target) => {
-    const file = path.resolve(root, from, target);
+    const name = referencedPath(target);
+    if (!name || ELSEWHERE.test(target)) return;
+    const file = path.resolve(root, from, name);
     if (!file.startsWith(root) || !existsSync(file)) missing.push(`${from || 'root'} → ${target}`);
   };
   for (const file of await filesUnder(root)) {
@@ -87,7 +118,7 @@ export async function missingReferences(dir, extra = []) {
       for (const [, ref] of source.matchAll(/getURL\('([^']+)'\)/g)) check('', ref);
     } else if (file.endsWith('.html')) {
       const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, ref] of source.matchAll(/(?:src|href)="([^"#:]+)"/g)) check(from, ref);
+      for (const [, ref] of source.matchAll(/(?:src|href)="([^"]+)"/g)) check(from, ref);
     }
   }
   const manifest = JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8'));

package/src/testing/saved-groups.d.ts

@@ -0,0 +1,33 @@
+export type SavedTabGroup = {
+    /**
+     * Its title.
+     */
+    title: string;
+    /**
+     * Whether it's pinned to the saved groups bar.
+     */
+    pinned: boolean;
+    /**
+     * Its tabs' addresses, in order.
+     */
+    urls: string[];
+};
+export type ProtoField = {
+    field: number;
+    value: number | Buffer;
+};
+/**
+ * Chrome's saved tab groups in a closed profile.
+ *
+ * @param {string} profile - The profile folder (as `extensionProfile` gives it).
+ * @returns {Promise<SavedTabGroup[]>} The saved groups, in no particular order; none when the
+ *   profile has no store yet.
+ * @throws {Error} When the store has compacted tables this doesn't read.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const { worker, close } = await profile.launch();
+ * await worker.evaluate(async () => chrome.tabGroups.update(await chrome.tabs.group({tabIds: [tabId]}), {title: 'Research'}));
+ * await close();
+ * const groups = await savedTabGroups(profile.dir); // → [{title: 'Research', pinned: true, urls: [...]}]
+ */
+export declare function savedTabGroups(profile: string): Promise<SavedTabGroup[]>;

package/src/testing/saved-groups.js

@@ -0,0 +1,222 @@
+/**
+ * Chrome's saved tab groups, read from a closed profile: no extension API lists them and their
+ * UI (the saved groups bar, the Tab groups menu) is native, so e2e checks read the store itself.
+ *
+ * Chromium keeps them in the profile's `Sync Data/LevelDB` (a DataTypeStore, kept even when
+ * signed out), one record per group and one per tab, keyed `saved_tab_group-dt-<guid>`. Each
+ * value is a `SavedTabGroupData` proto whose field 2 is the `SavedTabGroupSpecifics`
+ * (components/sync/protocol/saved_tab_group_specifics.proto): 1 guid, 4 group (2 title,
+ * 3 colour, 4 pinned position: present when pinned to the bar), 5 tab (1 group guid, 2 position,
+ * 3 url). A fresh test profile never fills a LevelDB log (4 MB) so everything is in `*.log`
+ * files, which this reads; it refuses a store that has compacted tables.
+ *
+ * Read only after the browser has closed, so every write is on disk.
+ *
+ * @module testing/saved-groups
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * A saved group as Chrome keeps it.
+ *
+ * @typedef {object} SavedTabGroup
+ * @property {string} title Its title.
+ * @property {boolean} pinned Whether it's pinned to the saved groups bar.
+ * @property {string[]} urls Its tabs' addresses, in order.
+ */
+
+/**
+ * One protobuf field: its number and value (a number for varints, the bytes for the rest).
+ *
+ * @typedef {{field: number, value: number | Buffer}} ProtoField
+ */
+
+const KEY_PREFIX = 'saved_tab_group-dt-';
+/** LevelDB log blocks: 32 KB, each record with a 7-byte header (checksum, length, type). */
+const BLOCK = 32768;
+const HEADER = 7;
+/** Record types: a whole batch, or its first, middle or last fragment. */
+const FULL = 1;
+const FIRST = 2;
+const MIDDLE = 3;
+const LAST = 4;
+
+/**
+ * Read a varint (LevelDB lengths, protobuf keys and values). Numbers past 2^53 lose precision,
+ * which only affects timestamps this never reads.
+ *
+ * @param {Buffer} buf - The bytes.
+ * @param {number} at - Where it starts.
+ * @returns {[value: number, next: number]} Its value and the offset after it.
+ */
+function varint(buf, at) {
+  let value = 0;
+  let scale = 1;
+  let byte;
+  do {
+    byte = buf[at++];
+    value += (byte & 0x7f) * scale;
+    scale *= 128;
+  } while (byte & 0x80);
+  return [value, at];
+}
+
+/**
+ * The write batches in one LevelDB log file, fragments joined.
+ *
+ * @param {Buffer} buf - The file.
+ * @returns {Buffer[]} Its batches, in order.
+ */
+function batches(buf) {
+  /** @type {Buffer[]} */
+  const out = [];
+  /** @type {Buffer[]} */
+  let pending = [];
+  let at = 0;
+  while (at + HEADER <= buf.length) {
+    const left = BLOCK - (at % BLOCK);
+    if (left < HEADER) {
+      at += left; // Block trailer: zero padding.
+      continue;
+    }
+    const length = buf.readUInt16LE(at + 4);
+    const type = buf[at + 6];
+    if (type === 0 && length === 0) {
+      at += left; // Pre-allocated, unwritten space.
+      continue;
+    }
+    const data = buf.subarray(at + HEADER, at + HEADER + length);
+    at += HEADER + length;
+    if (type === FULL) out.push(data);
+    else if (type === FIRST) pending = [data];
+    else if (type === MIDDLE) pending.push(data);
+    else if (type === LAST) out.push(Buffer.concat([...pending, data]));
+  }
+  return out;
+}
+
+/**
+ * Apply one batch to the live keys: puts set a key, deletes remove it.
+ *
+ * @param {Buffer} batch - Sequence (8 bytes), count (4), then each tagged put or delete.
+ * @param {Map<string, Buffer>} live - The keys, changed in place.
+ */
+function apply(batch, live) {
+  const count = batch.readUInt32LE(8);
+  let at = 12;
+  for (let i = 0; i < count; i++) {
+    const put = batch[at++] === 1;
+    let length;
+    [length, at] = varint(batch, at);
+    const key = batch.subarray(at, at + length).toString('latin1');
+    at += length;
+    if (!put) {
+      live.delete(key);
+      continue;
+    }
+    [length, at] = varint(batch, at);
+    live.set(key, batch.subarray(at, at + length));
+    at += length;
+  }
+}
+
+/**
+ * The fields of one protobuf message (one level).
+ *
+ * @param {Buffer} buf - The message.
+ * @returns {ProtoField[]} Its fields, in order.
+ */
+function fields(buf) {
+  /** @type {ProtoField[]} */
+  const out = [];
+  let at = 0;
+  while (at < buf.length) {
+    let key;
+    [key, at] = varint(buf, at);
+    const field = Math.floor(key / 8);
+    const wire = key % 8;
+    if (wire === 0) {
+      let value;
+      [value, at] = varint(buf, at);
+      out.push({ field, value });
+    } else if (wire === 2) {
+      let length;
+      [length, at] = varint(buf, at);
+      out.push({ field, value: buf.subarray(at, at + length) });
+      at += length;
+    } else if (wire === 1 || wire === 5) {
+      const size = wire === 1 ? 8 : 4;
+      out.push({ field, value: buf.subarray(at, at + size) });
+      at += size;
+    } else {
+      throw new Error(`Unexpected protobuf wire type ${wire}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * A field's bytes.
+ *
+ * @param {ProtoField[]} message - The message's fields.
+ * @param {number} field - The field number.
+ * @returns {Buffer | undefined} Its bytes, when present and not a number.
+ */
+const bytesOf = (message, field) => {
+  const value = message.find((f) => f.field === field)?.value;
+  return Buffer.isBuffer(value) ? value : undefined;
+};
+
+/**
+ * Chrome's saved tab groups in a closed profile.
+ *
+ * @param {string} profile - The profile folder (as `extensionProfile` gives it).
+ * @returns {Promise<SavedTabGroup[]>} The saved groups, in no particular order; none when the
+ *   profile has no store yet.
+ * @throws {Error} When the store has compacted tables this doesn't read.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const { worker, close } = await profile.launch();
+ * await worker.evaluate(async () => chrome.tabGroups.update(await chrome.tabs.group({tabIds: [tabId]}), {title: 'Research'}));
+ * await close();
+ * const groups = await savedTabGroups(profile.dir); // → [{title: 'Research', pinned: true, urls: [...]}]
+ */
+export async function savedTabGroups(profile) {
+  const dir = path.join(profile, 'Default', 'Sync Data', 'LevelDB');
+  const files = await readdir(dir).catch(() => /** @type {string[]} */ ([]));
+  if (files.some((file) => file.endsWith('.ldb'))) throw new Error(`${dir} has compacted tables; only logs are read`);
+  /** @type {Map<string, Buffer>} */
+  const live = new Map();
+  for (const file of files.filter((name) => name.endsWith('.log')).sort()) {
+    for (const batch of batches(await readFile(path.join(dir, file)))) apply(batch, live);
+  }
+
+  /** @type {Map<string, SavedTabGroup>} */
+  const groups = new Map();
+  /** @type {{group: string, position: number, url: string}[]} */
+  const tabs = [];
+  for (const [key, value] of live) {
+    if (!key.startsWith(KEY_PREFIX)) continue;
+    const specifics = bytesOf(fields(value), 2);
+    if (!specifics) continue;
+    const spec = fields(specifics);
+    const guid = bytesOf(spec, 1)?.toString('utf8') ?? '';
+    const group = bytesOf(spec, 4);
+    const tab = bytesOf(spec, 5);
+    if (group) {
+      const g = fields(group);
+      groups.set(guid, { title: bytesOf(g, 2)?.toString('utf8') ?? '', pinned: g.some((f) => f.field === 4), urls: [] });
+    } else if (tab) {
+      const t = fields(tab);
+      const position = t.find((f) => f.field === 2)?.value;
+      tabs.push({
+        group: bytesOf(t, 1)?.toString('utf8') ?? '',
+        position: typeof position === 'number' ? position : 0,
+        url: bytesOf(t, 3)?.toString('utf8') ?? '',
+      });
+    }
+  }
+  for (const tab of tabs.sort((a, b) => a.position - b.position)) groups.get(tab.group)?.urls.push(tab.url);
+  return [...groups.values()];
+}

package/src/testing/server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A local web server for end-to-end test pages: a site for the content
+ * script to run on, answering each path from a table (or a function), on
+ * 127.0.0.1 so a test build's host permission can cover it.
+ *
+ * @module testing/server
+ */
+import type { IncomingMessage, Server } from 'node:http';
+export type Reply = string | Uint8Array | {
+    body: string | Uint8Array;
+    type?: string;
+    status?: number;
+    headers?: Record<string, string>;
+};
+export type Routes = Readonly<Record<string, Reply>> | ReadonlyMap<string, Reply> | ((pathname: string, request: IncomingMessage) => Reply | undefined | Promise<Reply | undefined>);
+export type TestServer = {
+    /**
+     * Node's server.
+     */
+    server: Server;
+    /**
+     * The port it listens on.
+     */
+    port: number;
+    /**
+     * `http://127.0.0.1:<port>`.
+     */
+    origin: string;
+    /**
+     * Drop open connections and stop listening.
+     */
+    close: () => Promise<void>;
+};
+/**
+ * Serve `routes` on 127.0.0.1.
+ *
+ * @param {Routes} routes - Path → page, or a function of the path.
+ * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @returns {Promise<TestServer>} The listening server.
+ * @example
+ * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
+ * await page.goto(`${site.origin}/`);
+ * await site.close();
+ */
+export declare function serve(routes: Routes, { port }?: {
+    port?: number;
+}): Promise<TestServer>;

package/src/testing/server.js

@@ -0,0 +1,90 @@
+/**
+ * A local web server for end-to-end test pages: a site for the content
+ * script to run on, answering each path from a table (or a function), on
+ * 127.0.0.1 so a test build's host permission can cover it.
+ *
+ * @module testing/server
+ */
+
+import { createServer } from 'node:http';
+
+/** @import { IncomingMessage, Server } from 'node:http' */
+
+/**
+ * What a path answers: a body (sent as UTF-8 HTML), or a body with its own
+ * type, status and headers.
+ *
+ * @typedef {string | Uint8Array | {body: string | Uint8Array, type?: string, status?: number, headers?: Record<string, string>}} Reply
+ */
+
+/**
+ * The site: path (without the query) → reply, as an object or a `Map` (which
+ * a test may change as it goes), or a function of the path; no reply is a 404.
+ *
+ * @typedef {Readonly<Record<string, Reply>> | ReadonlyMap<string, Reply>
+ *   | ((pathname: string, request: IncomingMessage) => Reply | undefined | Promise<Reply | undefined>)} Routes
+ */
+
+/**
+ * A running test site.
+ *
+ * @typedef {object} TestServer
+ * @property {Server} server Node's server.
+ * @property {number} port The port it listens on.
+ * @property {string} origin `http://127.0.0.1:<port>`.
+ * @property {() => Promise<void>} close Drop open connections and stop listening.
+ */
+
+const HTML = 'text/html; charset=utf-8';
+
+/**
+ * The reply for a path.
+ *
+ * @param {Routes} routes - The site.
+ * @param {string} pathname - The request's path.
+ * @param {IncomingMessage} request - The request.
+ * @returns {Promise<Reply | undefined>} What to send; `undefined` for a 404.
+ */
+async function replyFor(routes, pathname, request) {
+  if (typeof routes === 'function') return routes(pathname, request);
+  if (routes instanceof Map) return routes.get(pathname);
+  const table = /** @type {Readonly<Record<string, Reply>>} */ (routes);
+  return Object.hasOwn(table, pathname) ? table[pathname] : undefined;
+}
+
+/**
+ * Serve `routes` on 127.0.0.1.
+ *
+ * @param {Routes} routes - Path → page, or a function of the path.
+ * @param {{port?: number}} [options] - `port`: a fixed port (default: any free one).
+ * @returns {Promise<TestServer>} The listening server.
+ * @example
+ * const site = await serve({'/': '<!doctype html><textarea></textarea>'});
+ * await page.goto(`${site.origin}/`);
+ * await site.close();
+ */
+export async function serve(routes, { port = 0 } = {}) {
+  const server = createServer(async (request, response) => {
+    const { pathname } = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const reply = await replyFor(routes, pathname, request);
+    if (reply === undefined) {
+      response.writeHead(404, { 'Content-Type': HTML });
+      response.end('');
+      return;
+    }
+    const { body, type = HTML, status = 200, headers = {} } = typeof reply === 'string' || reply instanceof Uint8Array ? { body: reply } : reply;
+    response.writeHead(status, { 'Content-Type': type, ...headers });
+    response.end(body);
+  });
+  await new Promise((resolve) => server.listen(port, '127.0.0.1', () => resolve(undefined)));
+  const address = /** @type {import('node:net').AddressInfo} */ (server.address());
+  return {
+    server,
+    port: address.port,
+    origin: `http://127.0.0.1:${address.port}`,
+    close() {
+      server.closeAllConnections();
+      return new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/testing/warnings.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Chrome's own install warnings for a manifest ("Read your browsing
+ * history"), the lines its install dialog and the Chrome Web Store list, read
+ * with `chrome.management.getPermissionWarningsByManifest` (no `management`
+ * permission needed) in a loaded extension's service worker. For an e2e check
+ * that a permission adds no warning, or that the warnings are exactly the
+ * ones the store listing explains.
+ *
+ * @module testing/warnings
+ */
+import type { Worker } from 'playwright';
+export type Manifest = Record<string, unknown>;
+/** @import { Worker } from 'playwright' */
+/**
+ * A manifest, as `manifest.json` parses.
+ *
+ * @typedef {Record<string, unknown>} Manifest
+ */
+/**
+ * The manifest less some permissions (from `permissions`, `optional_permissions`
+ * and `host_permissions`). Pure: `manifest` is left as it was.
+ *
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions (or host patterns) to leave out.
+ * @returns {Manifest} A copy without them.
+ * @example
+ * withoutPermissions({permissions: ['tabs', 'alarms']}, ['alarms']); // → {permissions: ['tabs']}
+ */
+export declare function withoutPermissions(manifest: Manifest, names: readonly string[]): Manifest;
+/**
+ * Chrome's install warnings for a manifest, as this browser words them.
+ *
+ * @param {Worker} worker - A loaded extension's service worker (`launchExtension`'s `worker`).
+ * @param {Manifest} manifest - The manifest to ask about (it needn't be the loaded extension's).
+ * @returns {Promise<string[]>} The warnings, in Chrome's order.
+ * @example
+ * assert.deepEqual(await installWarnings(worker, manifest), ['Read your browsing history']);
+ */
+export declare function installWarnings(worker: Worker, manifest: Manifest): Promise<string[]>;
+/**
+ * Chrome's install warnings for a manifest, with and without some permissions,
+ * and the ones only the permissions bring (a warning they reword counts).
+ *
+ * @param {Worker} worker - A loaded extension's service worker.
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions in question.
+ * @returns {Promise<{warnings: string[], without: string[], added: string[]}>} The warnings with
+ *   them, without them, and those in the first list only.
+ * @example
+ * const { warnings, added } = await warningsAddedBy(worker, manifest, ['alarms']);
+ * assert.deepEqual(added, []); // alarms asks the user nothing
+ */
+export declare function warningsAddedBy(worker: Worker, manifest: Manifest, names: readonly string[]): Promise<{
+    warnings: string[];
+    without: string[];
+    added: string[];
+}>;

package/src/testing/warnings.js

@@ -0,0 +1,69 @@
+/**
+ * Chrome's own install warnings for a manifest ("Read your browsing
+ * history"), the lines its install dialog and the Chrome Web Store list, read
+ * with `chrome.management.getPermissionWarningsByManifest` (no `management`
+ * permission needed) in a loaded extension's service worker. For an e2e check
+ * that a permission adds no warning, or that the warnings are exactly the
+ * ones the store listing explains.
+ *
+ * @module testing/warnings
+ */
+
+/** @import { Worker } from 'playwright' */
+
+/**
+ * A manifest, as `manifest.json` parses.
+ *
+ * @typedef {Record<string, unknown>} Manifest
+ */
+
+/**
+ * The manifest less some permissions (from `permissions`, `optional_permissions`
+ * and `host_permissions`). Pure: `manifest` is left as it was.
+ *
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions (or host patterns) to leave out.
+ * @returns {Manifest} A copy without them.
+ * @example
+ * withoutPermissions({permissions: ['tabs', 'alarms']}, ['alarms']); // → {permissions: ['tabs']}
+ */
+export function withoutPermissions(manifest, names) {
+  const copy = { ...manifest };
+  for (const key of ['permissions', 'optional_permissions', 'host_permissions']) {
+    const list = manifest[key];
+    if (Array.isArray(list)) copy[key] = list.filter((name) => !names.includes(name));
+  }
+  return copy;
+}
+
+/**
+ * Chrome's install warnings for a manifest, as this browser words them.
+ *
+ * @param {Worker} worker - A loaded extension's service worker (`launchExtension`'s `worker`).
+ * @param {Manifest} manifest - The manifest to ask about (it needn't be the loaded extension's).
+ * @returns {Promise<string[]>} The warnings, in Chrome's order.
+ * @example
+ * assert.deepEqual(await installWarnings(worker, manifest), ['Read your browsing history']);
+ */
+export function installWarnings(worker, manifest) {
+  return worker.evaluate((text) => chrome.management.getPermissionWarningsByManifest(text), JSON.stringify(manifest));
+}
+
+/**
+ * Chrome's install warnings for a manifest, with and without some permissions,
+ * and the ones only the permissions bring (a warning they reword counts).
+ *
+ * @param {Worker} worker - A loaded extension's service worker.
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions in question.
+ * @returns {Promise<{warnings: string[], without: string[], added: string[]}>} The warnings with
+ *   them, without them, and those in the first list only.
+ * @example
+ * const { warnings, added } = await warningsAddedBy(worker, manifest, ['alarms']);
+ * assert.deepEqual(added, []); // alarms asks the user nothing
+ */
+export async function warningsAddedBy(worker, manifest, names) {
+  const warnings = await installWarnings(worker, manifest);
+  const without = await installWarnings(worker, withoutPermissions(manifest, names));
+  return { warnings, without, added: warnings.filter((warning) => !without.includes(warning)) };
+}