@arraypress/extension-kit 0.0.0-stage → 1.0.0

package/src/testing/e2e.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Helpers for end-to-end tests that load an unpacked extension into
+ * Playwright's Chromium: launching it, waiting for a condition, emulating
+ * the colour scheme inside the offscreen document (which Playwright doesn't
+ * list as a page), and recording `chrome.action.setIcon` calls (Chrome has no
+ * getter for an action's icon).
+ *
+ * @module testing/e2e
+ */
+import type { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright';
+export type LaunchedExtension = {
+    /**
+     * The persistent context it's loaded in.
+     */
+    context: BrowserContext;
+    /**
+     * Its service worker.
+     */
+    worker: Worker;
+    /**
+     * Its id, the host of its pages.
+     */
+    extensionId: string;
+    /**
+     * `chrome-extension://<id>/<page>`.
+     */
+    url: (page?: string) => string;
+    /**
+     * Close the browser and delete its profile.
+     */
+    close: () => Promise<void>;
+};
+export type LaunchOptions = NonNullable<Parameters<BrowserType['launchPersistentContext']>[1]> & {
+    prefix?: string;
+};
+/** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
+/**
+ * A launched extension.
+ *
+ * @typedef {object} LaunchedExtension
+ * @property {BrowserContext} context The persistent context it's loaded in.
+ * @property {Worker} worker Its service worker.
+ * @property {string} extensionId Its id, the host of its pages.
+ * @property {(page?: string) => string} url `chrome-extension://<id>/<page>`.
+ * @property {() => Promise<void>} close Close the browser and delete its profile.
+ */
+/**
+ * What `launchExtension` takes: Playwright's persistent-context options, a
+ * name prefix for the temporary profile, and more Chromium switches.
+ *
+ * @typedef {NonNullable<Parameters<BrowserType['launchPersistentContext']>[1]> & {prefix?: string}} LaunchOptions
+ */
+/**
+ * Poll `fn` until it returns something truthy.
+ *
+ * @template T
+ * @param {() => T | Promise<T>} fn - The check.
+ * @param {string} what - What's awaited, for the timeout's message.
+ * @param {number} [timeout] - Give up after this many ms. Default 5000.
+ * @returns {Promise<NonNullable<T>>} The first truthy value.
+ * @throws {Error} "Timed out waiting for <what>".
+ */
+export declare function until<T>(fn: () => T | Promise<T>, what: string, timeout?: number): Promise<NonNullable<T>>;
+/**
+ * Load the unpacked extension at `dir` into a fresh profile and wait for its
+ * service worker.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - Playwright's context options (`locale`, `viewport`, …), plus
+ *   `prefix` (the temporary profile's name prefix) and `args` (more Chromium switches).
+ * @returns {Promise<LaunchedExtension>} The running extension.
+ * @example
+ * const { context, worker, url, close } = await launchExtension(chromium, 'extension');
+ * const page = await context.newPage();
+ * await page.goto(url('options/options.html'));
+ */
+export declare function launchExtension(chromium: BrowserType, dir: string, { prefix, args, ...options }?: LaunchOptions): Promise<LaunchedExtension>;
+/**
+ * Emulate colour schemes in the offscreen document: one CDP session attached
+ * to it, reused for every change.
+ *
+ * @param {CDPSession} cdp - A browser-level session (`context.newCDPSession(page)`).
+ * @param {string} [suffix] - How the document's address ends. Default `/offscreen/offscreen.html`.
+ * @returns {Promise<(scheme: 'light' | 'dark') => Promise<unknown>>} Sets the document's scheme.
+ * @throws {Error} When no such document is open.
+ */
+export declare function offscreenEmulator(cdp: CDPSession, suffix?: string): Promise<(scheme: 'light' | 'dark') => Promise<unknown>>;
+/**
+ * Wrap the worker's real `chrome.action.setIcon` so each call is recorded once
+ * Chrome has taken it (a path Chrome can't load fails, and isn't recorded).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @returns {Promise<() => Promise<unknown[]>>} Reads the recorded `path`s, oldest first.
+ */
+export declare function recordIconCalls(worker: Worker): Promise<() => Promise<unknown[]>>;
+export type CheckRunner = {
+    /**
+     * Run one check; resolves to whether it passed.
+     */
+    check: (name: string, fn: () => unknown) => Promise<boolean>;
+    /**
+     * Print the tally, and exit with 1 if anything failed.
+     */
+    finish: () => void;
+};
+/**
+ * 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 {() => 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.
+ *
+ * @returns {CheckRunner} The runner.
+ * @example
+ * const { check, finish } = checkRunner();
+ * await check('the menu opens', async () => { … });
+ * finish();
+ */
+export declare function checkRunner(): CheckRunner;
+export type SchemePage = {
+    /**
+     * From the extension's root, e.g. `options/options.html`.
+     */
+    path: string;
+    /**
+     * Resolves once the
+     * page's script has run. Default: the load event.
+     */
+    ready?: (page: Page) => Promise<unknown>;
+};
+/**
+ * A page of the extension that reports its colour scheme.
+ *
+ * @typedef {object} SchemePage
+ * @property {string} path From the extension's root, e.g. `options/options.html`.
+ * @property {(page: Page) => Promise<unknown>} [ready] Resolves once the
+ *   page's script has run. Default: the load event.
+ */
+/**
+ * The light/dark toolbar glyph, end to end, for an extension wired with
+ * `startToolbarTheme`, `watchSchemeOffscreen` and `watchColorScheme`:
+ *
+ * 1. the worker keeps exactly one offscreen document open, for MATCH_MEDIA;
+ * 2. each page shows the dark glyph when dark and the light one when light,
+ *    a second page in an unchanged scheme sends nothing, and `toolbarDark`
+ *    stays out of Chrome Sync;
+ * 3. with no page open, the offscreen document alone follows a change.
+ *
+ * Throws (an assertion) at the first thing that's wrong; logs a ✔ line per step.
+ *
+ * @param {LaunchedExtension} launched - From {@link launchExtension}.
+ * @param {readonly SchemePage[]} pages - The pages that report; the first is opened twice.
+ * @param {{light: unknown, dark: unknown}} icons - `toolbarIcon(false)` and `toolbarIcon(true)`.
+ * @returns {Promise<void>}
+ */
+export declare function checkToolbarTheme({ context, worker, url }: LaunchedExtension, pages: readonly SchemePage[], icons: {
+    light: unknown;
+    dark: unknown;
+}): Promise<void>;

package/src/testing/e2e.js

@@ -0,0 +1,272 @@
+/**
+ * Helpers for end-to-end tests that load an unpacked extension into
+ * Playwright's Chromium: launching it, waiting for a condition, emulating
+ * the colour scheme inside the offscreen document (which Playwright doesn't
+ * list as a page), and recording `chrome.action.setIcon` calls (Chrome has no
+ * getter for an action's icon).
+ *
+ * @module testing/e2e
+ */
+
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+/** @import { BrowserContext, BrowserType, CDPSession, Page, Worker } from 'playwright' */
+
+/**
+ * A launched extension.
+ *
+ * @typedef {object} LaunchedExtension
+ * @property {BrowserContext} context The persistent context it's loaded in.
+ * @property {Worker} worker Its service worker.
+ * @property {string} extensionId Its id, the host of its pages.
+ * @property {(page?: string) => string} url `chrome-extension://<id>/<page>`.
+ * @property {() => Promise<void>} close Close the browser and delete its profile.
+ */
+
+/**
+ * What `launchExtension` takes: Playwright's persistent-context options, a
+ * name prefix for the temporary profile, and more Chromium switches.
+ *
+ * @typedef {NonNullable<Parameters<BrowserType['launchPersistentContext']>[1]> & {prefix?: string}} LaunchOptions
+ */
+
+/**
+ * Poll `fn` until it returns something truthy.
+ *
+ * @template T
+ * @param {() => T | Promise<T>} fn - The check.
+ * @param {string} what - What's awaited, for the timeout's message.
+ * @param {number} [timeout] - Give up after this many ms. Default 5000.
+ * @returns {Promise<NonNullable<T>>} The first truthy value.
+ * @throws {Error} "Timed out waiting for <what>".
+ */
+export async function until(fn, what, timeout = 5000) {
+  const end = Date.now() + timeout;
+  for (;;) {
+    const value = await fn();
+    if (value) return /** @type {NonNullable<T>} */ (value);
+    if (Date.now() > end) throw new Error(`Timed out waiting for ${what}`);
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+/**
+ * Load the unpacked extension at `dir` into a fresh profile and wait for its
+ * service worker.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - Playwright's context options (`locale`, `viewport`, …), plus
+ *   `prefix` (the temporary profile's name prefix) and `args` (more Chromium switches).
+ * @returns {Promise<LaunchedExtension>} The running extension.
+ * @example
+ * const { context, worker, url, close } = await launchExtension(chromium, 'extension');
+ * const page = await context.newPage();
+ * await page.goto(url('options/options.html'));
+ */
+export async function launchExtension(chromium, dir, { prefix = 'extension-', args = [], ...options } = {}) {
+  const tmp = await mkdtemp(path.join(tmpdir(), prefix));
+  const context = await chromium.launchPersistentContext(path.join(tmp, 'profile'), {
+    channel: 'chromium',
+    ...options,
+    args: [`--disable-extensions-except=${dir}`, `--load-extension=${dir}`, ...args],
+  });
+  const worker = context.serviceWorkers()[0] ?? await context.waitForEvent('serviceworker');
+  const extensionId = new URL(worker.url()).host;
+  return {
+    context,
+    worker,
+    extensionId,
+    url: (page = '') => `chrome-extension://${extensionId}/${page}`,
+    async close() {
+      await context.close();
+      await rm(tmp, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Emulate colour schemes in the offscreen document: one CDP session attached
+ * to it, reused for every change.
+ *
+ * @param {CDPSession} cdp - A browser-level session (`context.newCDPSession(page)`).
+ * @param {string} [suffix] - How the document's address ends. Default `/offscreen/offscreen.html`.
+ * @returns {Promise<(scheme: 'light' | 'dark') => Promise<unknown>>} Sets the document's scheme.
+ * @throws {Error} When no such document is open.
+ */
+export async function offscreenEmulator(cdp, suffix = '/offscreen/offscreen.html') {
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  const target = targetInfos.find((info) => info.url.endsWith(suffix));
+  if (!target) throw new Error(`No offscreen document ending ${suffix} is open`);
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId: target.targetId, flatten: false });
+  let id = 0;
+  return (scheme) => cdp.send('Target.sendMessageToTarget', {
+    sessionId,
+    message: JSON.stringify({
+      id: ++id,
+      method: 'Emulation.setEmulatedMedia',
+      params: { features: [{ name: 'prefers-color-scheme', value: scheme }] },
+    }),
+  });
+}
+
+/**
+ * Wrap the worker's real `chrome.action.setIcon` so each call is recorded once
+ * Chrome has taken it (a path Chrome can't load fails, and isn't recorded).
+ *
+ * @param {Worker} worker - The extension's service worker.
+ * @returns {Promise<() => Promise<unknown[]>>} Reads the recorded `path`s, oldest first.
+ */
+export async function recordIconCalls(worker) {
+  await worker.evaluate(() => {
+    const calls = /** @type {unknown[]} */ ([]);
+    Object.assign(globalThis, { iconCalls: calls });
+    const real = chrome.action.setIcon.bind(chrome.action);
+    chrome.action.setIcon = /** @type {typeof chrome.action.setIcon} */ (async (/** @type {chrome.action.TabIconDetails} */ details) => {
+      await real(details);
+      calls.push(details.path);
+    });
+  });
+  return () => worker.evaluate(() => /** @type {{iconCalls: unknown[]}} */ (/** @type {unknown} */ (globalThis)).iconCalls);
+}
+
+/**
+ * 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 {() => 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.
+ *
+ * @returns {CheckRunner} The runner.
+ * @example
+ * const { check, finish } = checkRunner();
+ * await check('the menu opens', async () => { … });
+ * finish();
+ */
+export function checkRunner() {
+  /** @type {string[]} */
+  const failures = [];
+  let passed = 0;
+  return {
+    async check(name, fn) {
+      try {
+        await fn();
+        passed++;
+        console.log(`  ✓ ${name}`);
+        return true;
+      } catch (error) {
+        failures.push(name);
+        console.log(`  ✗ ${name}\n    ${String(/** @type {Error} */ (error)?.message ?? error).split('\n').join('\n    ')}`);
+        return false;
+      }
+    },
+    finish() {
+      console.log(`\n${passed} passed, ${failures.length} failed`);
+      if (!failures.length) return;
+      for (const failure of failures) console.log(`  - ${failure}`);
+      process.exit(1);
+    },
+  };
+}
+
+/**
+ * A page of the extension that reports its colour scheme.
+ *
+ * @typedef {object} SchemePage
+ * @property {string} path From the extension's root, e.g. `options/options.html`.
+ * @property {(page: Page) => Promise<unknown>} [ready] Resolves once the
+ *   page's script has run. Default: the load event.
+ */
+
+/**
+ * The light/dark toolbar glyph, end to end, for an extension wired with
+ * `startToolbarTheme`, `watchSchemeOffscreen` and `watchColorScheme`:
+ *
+ * 1. the worker keeps exactly one offscreen document open, for MATCH_MEDIA;
+ * 2. each page shows the dark glyph when dark and the light one when light,
+ *    a second page in an unchanged scheme sends nothing, and `toolbarDark`
+ *    stays out of Chrome Sync;
+ * 3. with no page open, the offscreen document alone follows a change.
+ *
+ * Throws (an assertion) at the first thing that's wrong; logs a ✔ line per step.
+ *
+ * @param {LaunchedExtension} launched - From {@link launchExtension}.
+ * @param {readonly SchemePage[]} pages - The pages that report; the first is opened twice.
+ * @param {{light: unknown, dark: unknown}} icons - `toolbarIcon(false)` and `toolbarIcon(true)`.
+ * @returns {Promise<void>}
+ */
+export async function checkToolbarTheme({ context, worker, url }, pages, icons) {
+  /** @param {Page} page @param {SchemePage} entry */
+  const open = async (page, entry) => {
+    await page.goto(url(entry.path));
+    await (entry.ready ? entry.ready(page) : page.waitForLoadState('load'));
+  };
+
+  // 1. The watcher. Right after creation Chrome can list the document before its address is set.
+  assert.equal(await worker.evaluate(() => chrome.offscreen.Reason.MATCH_MEDIA), 'MATCH_MEDIA');
+  const offscreen = await until(async () => {
+    const found = await worker.evaluate(() => chrome.runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] }));
+    return found.length > 0 && found.every((info) => info.documentUrl?.endsWith('/offscreen/offscreen.html')) ? found : null;
+  }, 'the offscreen document');
+  assert.equal(offscreen.length, 1);
+  assert.equal(offscreen[0].documentUrl, url('offscreen/offscreen.html'));
+  console.log('✔ the background keeps one offscreen document open, for MATCH_MEDIA');
+
+  const calls = await recordIconCalls(worker);
+  const stored = () => worker.evaluate(async () => (await chrome.storage.local.get('toolbarDark')).toolbarDark);
+  const last = async () => JSON.stringify((await calls()).at(-1));
+  /** @param {unknown} icon @param {string} what */
+  const untilIcon = (icon, what) => until(async () => (await last()) === JSON.stringify(icon), what);
+
+  // The offscreen document follows this machine's real scheme: take it to dark, then light, so
+  // every step below starts from a known state (stored light, the document last saw light).
+  const blank = await context.newPage();
+  const cdp = await context.newCDPSession(blank);
+  const emulateOffscreen = await offscreenEmulator(cdp);
+  await emulateOffscreen('dark');
+  await until(async () => (await stored()) === true, 'the offscreen document to report dark');
+  await emulateOffscreen('light');
+  await until(async () => (await stored()) === false, 'the offscreen document to report light');
+
+  // 2. Each page, dark then light; a second page in the same scheme sends nothing.
+  for (const entry of pages) {
+    const page = await context.newPage();
+    await page.emulateMedia({ colorScheme: 'light' });
+    await open(page, entry);
+    await page.emulateMedia({ colorScheme: 'dark' });
+    await until(async () => (await stored()) === true, `${entry.path}: the dark scheme stored`);
+    await untilIcon(icons.dark, `${entry.path}: the dark glyph`);
+    await page.emulateMedia({ colorScheme: 'light' });
+    await until(async () => (await stored()) === false, `${entry.path}: the light scheme stored`);
+    await untilIcon(icons.light, `${entry.path}: the light glyph`);
+    await page.close();
+  }
+  const before = (await calls()).length;
+  const again = await context.newPage();
+  await again.emulateMedia({ colorScheme: 'light' });
+  await open(again, pages[0]);
+  await again.waitForTimeout(300);
+  assert.equal((await calls()).length, before);
+  await again.close();
+  assert.equal('toolbarDark' in await worker.evaluate(() => chrome.storage.sync.get(null)), false);
+  console.log('✔ a dark page shows the dark glyph, light the light one, a second light page nothing; toolbarDark stays in local');
+
+  // 3. No page open: the offscreen document alone follows a change.
+  for (const page of context.pages()) if (page.url().startsWith('chrome-extension://')) await page.close();
+  await emulateOffscreen('dark');
+  await untilIcon(icons.dark, 'the dark glyph from the offscreen document');
+  await emulateOffscreen('light');
+  await untilIcon(icons.light, 'the light glyph from the offscreen document');
+  await cdp.detach();
+  await blank.close();
+  console.log('✔ with no page open, the offscreen document swaps the glyph on a scheme change');
+}

package/src/testing/fake-storage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * An in-memory `chrome.storage` for tests, behaving as Chrome does: values
+ * are stored as JSON, `onChanged` fires only for values that changed, and
+ * sync refuses an item over its 8,192-byte quota and more than 120 writes
+ * (set or remove) a minute. Tests then check outcomes (what's stored), not
+ * calls.
+ *
+ * @module testing/fake-storage
+ */
+import type { StorageChange } from '../settings/storage.js';
+/** @import { StorageChange } from '../settings/storage.js' */
+/** Chrome Sync's write limit: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
+export declare const SYNC_WRITES_PER_MINUTE = 120;
+export type ChangeListener = (changes: Record<string, StorageChange>, area: string) => unknown;
+export type FakeArea = {
+    /**
+     * What it holds, to inspect (and seed) in tests.
+     */
+    data: Record<string, any>;
+    /**
+     * How many writes it has taken.
+     */
+    writes: number;
+    get: (keys?: string | string[] | null) => Promise<Record<string, any>>;
+    set: (items: Record<string, unknown>) => Promise<void>;
+    remove: (keys: string | string[]) => Promise<void>;
+};
+export type FakeChromeStorage = {
+    /**
+     * `chrome.storage.local`.
+     */
+    local: FakeArea;
+    /**
+     * `chrome.storage.sync`, with Chrome's quotas.
+     */
+    sync: FakeArea;
+    /**
+     * `chrome.storage.session`.
+     */
+    session: FakeArea;
+    /**
+     * `chrome.storage.onChanged`.
+     */
+    onChanged: {
+        addListener(listener: ChangeListener): void;
+    };
+    /**
+     * Waits for every listener, including the changes those listeners make.
+     */
+    settled: () => Promise<void>;
+};
+/**
+ * Make a fake `chrome.storage`.
+ *
+ * @param {object} [initial] - Starting contents and the clock.
+ * @param {Record<string, unknown>} [initial.local] - What local holds.
+ * @param {Record<string, unknown>} [initial.sync] - What sync holds.
+ * @param {Record<string, unknown>} [initial.session] - What session holds.
+ * @param {() => number} [initial.now] - The clock sync's write limit reads. Default `Date.now`.
+ * @returns {FakeChromeStorage} The fake.
+ * @example
+ * const storage = fakeChromeStorage({ sync: { days: 3 } });
+ * await store.save(storage, { days: 5 });
+ * assert.equal(storage.sync.data.days, 5);
+ */
+export declare function fakeChromeStorage({ local, sync, session, now }?: {
+    local?: Record<string, unknown>;
+    sync?: Record<string, unknown>;
+    session?: Record<string, unknown>;
+    now?: () => number;
+}): FakeChromeStorage;

package/src/testing/fake-storage.js

@@ -0,0 +1,145 @@
+/**
+ * An in-memory `chrome.storage` for tests, behaving as Chrome does: values
+ * are stored as JSON, `onChanged` fires only for values that changed, and
+ * sync refuses an item over its 8,192-byte quota and more than 120 writes
+ * (set or remove) a minute. Tests then check outcomes (what's stored), not
+ * calls.
+ *
+ * @module testing/fake-storage
+ */
+
+import { MAX_SYNC_ITEM_BYTES } from '../settings/storage.js';
+
+/** @import { StorageChange } from '../settings/storage.js' */
+
+/** Chrome Sync's write limit: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
+export const SYNC_WRITES_PER_MINUTE = 120;
+
+/**
+ * @typedef {(changes: Record<string, StorageChange>, area: string) => unknown} ChangeListener
+ */
+
+/**
+ * One fake storage area.
+ *
+ * @typedef {object} FakeArea
+ * @property {Record<string, any>} data What it holds, to inspect (and seed) in tests.
+ * @property {number} writes How many writes it has taken.
+ * @property {(keys?: string | string[] | null) => Promise<Record<string, any>>} get
+ * @property {(items: Record<string, unknown>) => Promise<void>} set
+ * @property {(keys: string | string[]) => Promise<void>} remove
+ */
+
+/**
+ * The fake `chrome.storage`.
+ *
+ * @typedef {object} FakeChromeStorage
+ * @property {FakeArea} local `chrome.storage.local`.
+ * @property {FakeArea} sync `chrome.storage.sync`, with Chrome's quotas.
+ * @property {FakeArea} session `chrome.storage.session`.
+ * @property {{addListener(listener: ChangeListener): void}} onChanged `chrome.storage.onChanged`.
+ * @property {() => Promise<void>} settled Waits for every listener, including the changes those listeners make.
+ */
+
+/**
+ * Copy a value the way storage does, through JSON.
+ *
+ * @param {unknown} value - Anything JSON-able, or undefined.
+ * @returns {any} The copy.
+ */
+const viaJson = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
+
+/**
+ * Make a fake `chrome.storage`.
+ *
+ * @param {object} [initial] - Starting contents and the clock.
+ * @param {Record<string, unknown>} [initial.local] - What local holds.
+ * @param {Record<string, unknown>} [initial.sync] - What sync holds.
+ * @param {Record<string, unknown>} [initial.session] - What session holds.
+ * @param {() => number} [initial.now] - The clock sync's write limit reads. Default `Date.now`.
+ * @returns {FakeChromeStorage} The fake.
+ * @example
+ * const storage = fakeChromeStorage({ sync: { days: 3 } });
+ * await store.save(storage, { days: 5 });
+ * assert.equal(storage.sync.data.days, 5);
+ */
+export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = Date.now } = {}) {
+  /** @type {ChangeListener[]} */
+  const listeners = [];
+  /** @type {unknown[]} */
+  const running = [];
+
+  /**
+   * @param {string} name
+   * @param {Record<string, unknown>} initialData
+   * @param {{quotaPerItem?: number, writesPerMinute?: number}} [limits]
+   * @returns {FakeArea}
+   */
+  function area(name, initialData, { quotaPerItem, writesPerMinute } = {}) {
+    /** @type {Record<string, any>} */
+    const data = viaJson(initialData);
+    /** @type {number[]} */
+    const recent = [];
+    /** @param {Record<string, StorageChange>} changes */
+    const fire = (changes) => {
+      if (!Object.keys(changes).length) return;
+      for (const listener of listeners) running.push(listener(viaJson(changes), name));
+    };
+    /** A write, counted against the per-minute limit; refused over it, as Chrome does. */
+    const take = () => {
+      if (writesPerMinute) {
+        while (recent.length && recent[0] <= now() - 60_000) recent.shift();
+        if (recent.length >= writesPerMinute) throw new Error('This request exceeds the MAX_WRITE_OPERATIONS_PER_MINUTE quota.');
+        recent.push(now());
+      }
+      fake.writes++;
+    };
+    /** @type {FakeArea} */
+    const fake = {
+      data,
+      writes: 0,
+      async get(keys) {
+        const wanted = keys == null ? Object.keys(data) : [keys].flat();
+        return Object.fromEntries(wanted.filter((key) => key in data).map((key) => [key, viaJson(data[key])]));
+      },
+      async set(items) {
+        for (const [key, value] of Object.entries(items)) {
+          if (quotaPerItem && key.length + JSON.stringify(value).length > quotaPerItem) {
+            throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
+          }
+        }
+        take();
+        /** @type {Record<string, StorageChange>} */
+        const changes = {};
+        for (const [key, value] of Object.entries(items)) {
+          if (JSON.stringify(data[key]) === JSON.stringify(value)) continue;
+          changes[key] = { oldValue: data[key], newValue: viaJson(value) };
+          data[key] = viaJson(value);
+        }
+        fire(changes);
+      },
+      async remove(keys) {
+        take();
+        /** @type {Record<string, StorageChange>} */
+        const changes = {};
+        for (const key of [keys].flat()) {
+          if (!(key in data)) continue;
+          changes[key] = { oldValue: data[key] };
+          delete data[key];
+        }
+        fire(changes);
+      },
+    };
+    return fake;
+  }
+
+  return {
+    local: area('local', local),
+    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
+    session: area('session', session),
+    onChanged: { addListener: (listener) => listeners.push(listener) },
+    async settled() {
+      while (running.length) await Promise.all(running.splice(0));
+    },
+  };
+}

package/src/testing/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * end-to-end tests, and checks for a packaging test. Node only.
+ *
+ * @module testing
+ */
+export { checkRunner, checkToolbarTheme, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';

package/src/testing/index.js

@@ -0,0 +1,10 @@
+/**
+ * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
+ * end-to-end tests, and checks for a packaging test. Node only.
+ *
+ * @module testing
+ */
+
+export { checkRunner, checkToolbarTheme, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
+export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';