@arraypress/extension-kit 1.1.0 → 1.2.0

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/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)) };
+}

package/src/ui/menu.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Chrome's action menu (cr-action-menu), the ⋮ menu of chrome://bookmarks and
+ * chrome://settings: a `<dialog class="menu">` of `role="menuitem"` buttons,
+ * shown modally over the button that opened it (or at the pointer, for a
+ * right-click) and kept on screen. A click outside it, Esc, Tab or the window
+ * losing focus closes it; ↑/↓ (wrapping), Home and End move between its
+ * items; and focus goes back to where it came from. Also the rows' ⋮ button,
+ * labelled "More actions for …" as Chrome labels its own.
+ *
+ * Sources: ui/webui/resources/cr_elements/cr_action_menu/cr_action_menu.ts
+ * (a modal `<dialog>`; a click on its backdrop closes it; the anchor gets the
+ * focus back; ↑/↓ wrap) and cr_icon_button with cr:more-vert.
+ *
+ * @module ui/menu
+ */
+/** The gap kept between a menu and the window's edges, in px. */
+export declare const MENU_EDGE = 8;
+export type MenuItem = {
+    /**
+     * Its text ("Rename").
+     */
+    label: string;
+    /**
+     * Runs once the menu has closed.
+     */
+    run: () => unknown;
+    /**
+     * Greyed out, and skipped by the arrow keys.
+     */
+    disabled?: boolean;
+};
+export type MenuEntry = MenuItem | 'separator';
+export type MenuPlace = {
+    /**
+     * The button that opened it.
+     */
+    anchor?: HTMLElement;
+    /**
+     * Without an anchor: the pointer's x (a right-click's `clientX`).
+     */
+    x?: number;
+    /**
+     * Without an anchor: the pointer's y.
+     */
+    y?: number;
+    /**
+     * The menu's name for screen readers ("Actions for Research").
+     */
+    label?: string;
+    /**
+     * Where focus goes when it closes. Default the anchor, else what had focus.
+     */
+    focusTo?: HTMLElement;
+};
+export type Box = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * One item: its text, what it does, and whether it's greyed out.
+ *
+ * @typedef {object} MenuItem
+ * @property {string} label Its text ("Rename").
+ * @property {() => unknown} run Runs once the menu has closed.
+ * @property {boolean} [disabled] Greyed out, and skipped by the arrow keys.
+ */
+/**
+ * An item, or `'separator'` for a line between groups of items.
+ *
+ * @typedef {MenuItem | 'separator'} MenuEntry
+ */
+/**
+ * Where a menu opens: over (or below) the button that opened it, or at a
+ * pointer position.
+ *
+ * @typedef {object} MenuPlace
+ * @property {HTMLElement} [anchor] The button that opened it.
+ * @property {number} [x] Without an anchor: the pointer's x (a right-click's `clientX`).
+ * @property {number} [y] Without an anchor: the pointer's y.
+ * @property {string} [label] The menu's name for screen readers ("Actions for Research").
+ * @property {HTMLElement} [focusTo] Where focus goes when it closes. Default the anchor, else what had focus.
+ */
+/**
+ * A rectangle in the window, as `getBoundingClientRect()` gives it.
+ *
+ * @typedef {{left: number, top: number, right: number, bottom: number}} Box
+ */
+/**
+ * Where to put a menu, so it stays on screen. Pure.
+ *
+ * Over an anchor (Chrome's way): the menu's top at the anchor's top and its
+ * end at the anchor's end; moved up to end at the anchor's bottom when it
+ * would leave the window below. Below an anchor: 4px under it, or above it
+ * when there's no room. At a point: its top-left there, or its bottom-left
+ * when there's no room below. Always at least {@link MENU_EDGE} from the
+ * window's edges.
+ *
+ * @param {{width: number, height: number}} size - The menu's size.
+ * @param {{width: number, height: number}} viewport - The window's (`innerWidth`, `innerHeight`).
+ * @param {{anchor?: Box, x?: number, y?: number, placement?: 'over' | 'below'}} where - The anchor's
+ *   box, or a point; `placement` says where it goes from an anchor (default `'over'`).
+ * @returns {{left: number, top: number}} The menu's top-left, in px.
+ * @example
+ * menuPosition({width: 160, height: 120}, {width: 800, height: 600}, {anchor: button.getBoundingClientRect()});
+ * // → {left: anchor.right - 160, top: anchor.top}
+ */
+export declare function menuPosition(size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, { anchor, x, y, placement }: {
+    anchor?: Box;
+    x?: number;
+    y?: number;
+    placement?: 'over' | 'below';
+}): {
+    left: number;
+    top: number;
+};
+/**
+ * Whether a point is inside a box (edges included). Pure.
+ *
+ * @param {Box} box - The box.
+ * @param {number} x - The point's x.
+ * @param {number} y - The point's y.
+ * @returns {boolean} True when inside.
+ */
+export declare function isInside(box: Box, x: number, y: number): boolean;
+export type MenuOptions = {
+    /**
+     * The menu element's id.
+     */
+    id?: string;
+    /**
+     * Where it opens from a button. Default `'over'`, as Chrome's.
+     */
+    placement?: 'over' | 'below';
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+export type ActionMenu = {
+    /**
+     * The `<dialog class="menu" role="menu">`, in the page's body.
+     */
+    element: HTMLDialogElement;
+    /**
+     * Fill it with `entries`
+     * and open it (closing it first if it's open).
+     */
+    open: (entries: readonly MenuEntry[], where: MenuPlace) => void;
+    /**
+     * Close it, if open, and return the focus.
+     */
+    close: () => void;
+};
+/**
+ * What {@link createMenu} takes.
+ *
+ * @typedef {object} MenuOptions
+ * @property {string} [id] The menu element's id.
+ * @property {'over' | 'below'} [placement] Where it opens from a button. Default `'over'`, as Chrome's.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A page's action menu.
+ *
+ * @typedef {object} ActionMenu
+ * @property {HTMLDialogElement} element The `<dialog class="menu" role="menu">`, in the page's body.
+ * @property {(entries: readonly MenuEntry[], where: MenuPlace) => void} open Fill it with `entries`
+ *   and open it (closing it first if it's open).
+ * @property {() => void} close Close it, if open, and return the focus.
+ */
+/**
+ * Make a page's action menu: one `<dialog class="menu">` that any number of
+ * ⋮ buttons (or right-clicks) open with their own items.
+ *
+ * @param {MenuOptions} [options] - Its id, placement and page.
+ * @returns {ActionMenu} The menu.
+ * @example
+ * const menu = createMenu();
+ * row.append(moreActionsButton(workspace.name, {
+ *   onClick: (button) => menu.open([
+ *     {label: 'Rename', run: () => rename(workspace)},
+ *     'separator',
+ *     {label: 'Delete', run: () => remove(workspace)},
+ *   ], {anchor: button}),
+ * }));
+ */
+export declare function createMenu({ id, placement, doc }?: MenuOptions): ActionMenu;
+export type MoreActionsOptions = {
+    /**
+     * The whole label, for a page that translates it. Default
+     * `More actions for “<name>”`, Chrome's words.
+     */
+    label?: string;
+    /**
+     * More classes, after `icon-button`.
+     */
+    className?: string;
+    /**
+     * In the tab order. Default true; false for a row that takes the
+     * focus itself and opens the menu from the keyboard.
+     */
+    focusable?: boolean;
+    /**
+     * Show the label on hover too (`title`). Default false.
+     */
+    tooltip?: boolean;
+    /**
+     * Opens its menu.
+     */
+    onClick?: (button: HTMLButtonElement, event: MouseEvent) => void;
+    /**
+     * The page. Default `document`.
+     */
+    doc?: Document;
+};
+/**
+ * What {@link moreActionsButton} takes.
+ *
+ * @typedef {object} MoreActionsOptions
+ * @property {string} [label] The whole label, for a page that translates it. Default
+ *   `More actions for “<name>”`, Chrome's words.
+ * @property {string} [className] More classes, after `icon-button`.
+ * @property {boolean} [focusable] In the tab order. Default true; false for a row that takes the
+ *   focus itself and opens the menu from the keyboard.
+ * @property {boolean} [tooltip] Show the label on hover too (`title`). Default false.
+ * @property {(button: HTMLButtonElement, event: MouseEvent) => void} [onClick] Opens its menu.
+ * @property {Document} [doc] The page. Default `document`.
+ */
+/**
+ * A row's ⋮ button: a 32px cr-icon-button with cr:more-vert (the
+ * stylesheet's `--icon-more-vert`, so the page needs no sprite), labelled for
+ * screen readers as Chrome labels its own.
+ *
+ * @param {string} name - What the row is ("Research"), for "More actions for “Research”".
+ * @param {MoreActionsOptions} [options] - Its label, classes, tab stop, tooltip and click.
+ * @returns {HTMLButtonElement} The button.
+ * @example
+ * row.append(moreActionsButton(site, {onClick: (button) => menu.open(siteItems(site), {anchor: button})}));
+ * // A translated label:
+ * moreActionsButton(name, {label: t('rowActions', name), className: 'row-menu', focusable: false});
+ */
+export declare function moreActionsButton(name: string, { label, className, focusable, tooltip, onClick, doc }?: MoreActionsOptions): HTMLButtonElement;