@arraypress/extension-kit 1.0.0 → 1.2.0

package/README.md

@@ -10,6 +10,8 @@ The pieces ArrayPress's Chrome extensions share, so each is written once:
   service worker shows the matching icon.
 - **About links**: README, Issues and PRIVACY.md in the extension's GitHub repository, plus
   package-time warnings for placeholder links.
+- **Chrome's page components**: the ⋮ action menu and its row button, the one-field dialog
+  ("Rename folder"), and the toast with Undo, built on the stylesheet's classes.
 - **Build and test helpers** (Node): toolbar icon rendering, zipping for the Chrome Web Store, a
   fake `chrome.storage`, Playwright helpers, packaging checks, and a copied-code guard.
 
@@ -132,6 +134,68 @@ At the end of `npm run package`, `printReleaseChecks(ABOUT_LINKS, REPOSITORY)` w
 link is a placeholder (`isPlaceholder`: example.com/.org/.net) and reminds you the repository must
 be public before the store listing goes live.
 
+## Page components
+
+Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
+Each takes `doc` (default `document`); the wording defaults to Chrome's English and takes a
+translation.
+
+### ⋮ menu (cr-action-menu)
+
+```js
+import { createMenu, moreActionsButton } from '../vendor/extension-kit/index.js';
+
+const menu = createMenu(); // one <dialog class="menu" role="menu"> for the page
+row.append(moreActionsButton(workspace.name, {
+  onClick: (anchor) => menu.open([
+    { label: 'Rename', run: () => rename(workspace) },
+    'separator',
+    { label: 'Delete', run: () => remove(workspace), disabled: locked },
+  ], { anchor }),
+}));
+// A right-click: menu.open(items, { x: event.clientX, y: event.clientY, focusTo: row });
+```
+
+It opens modally over its button, as Chrome's does (its top at the button's top, its end at the
+button's end), moved to stay 8px inside the window. A click outside, Esc, Tab or the window losing
+focus closes it; ↑/↓ (wrapping, past disabled items), Home and End move; focus goes back to the
+button (or `focusTo`); an item runs once the menu has closed. `createMenu({id, placement: 'below'})`
+opens it below the button instead. `menuPosition` and `isInside` are the pure geometry.
+
+`moreActionsButton(name, options)` is the 32px ⋮ icon button, labelled "More actions for “name”"
+(`label` for a translation), with `aria-haspopup="menu"`; its icon is the stylesheet's
+`.icon-more-vert` (`--icon-more-vert`, cr:more-vert), so the page needs no sprite. `className`,
+`tooltip` (a `title`) and `focusable: false` (out of the tab order, for a row that takes the focus)
+cover the rest.
+
+### One-field dialog (cr-dialog)
+
+```js
+const name = await askText({ title: 'Rename workspace', label: 'Name', value: workspace.name, maxLength: 200 });
+const site = await askText({
+  title: 'Add site', label: 'Site', action: 'Add',
+  validate: (text) => (siteFromInput(text) ? null : 'Enter a site, like example.com'),
+});
+```
+
+Resolves to the text, trimmed, or `null` when cancelled. The action button (default "Save") stays
+disabled while the text is blank or `validate` gives a reason, which shows under the field
+(`checkText` is that rule, pure). Enter presses the action button; Esc and Cancel cancel; the
+focus goes back to what had it, or to `returnTo` (an element, or a function asked at the end).
+One `#text-dialog` per page, made on first use.
+
+### Toast with Undo (cr-toast)
+
+```js
+const toast = createToast(); // at load, so screen readers know the live region
+toast.show(`Deleted “${workspace.name}”`, () => restore(workspace));
+toast.show('Copied'); // no Undo
+```
+
+`#toast` (`role="status"`), bottom left. A new message replaces the last and restarts the wait:
+10 seconds, as chrome://bookmarks's (`TOAST_MS`), or `duration` / `undoDuration`. Undo hides it
+and runs once. `undoLabel` translates the button.
+
 ## Build helpers (`@arraypress/extension-kit/build`)
 
 | Export | What it does |
@@ -157,11 +221,17 @@ except those listed, each with a reason:
 | Export | What it does |
 |---|---|
 | `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota and 120 writes a minute. `settled()` waits for listeners. |
-| `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), close()}`. |
+| `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
+| `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
+| `checkRunner()` | Named checks that report and go on: `check(name, fn)`, `fail(name)` for an error found outside a check, `finish()`. |
+| `serve(routes, {port})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. |
 | `until(fn, what, timeout?)` | Poll until truthy. |
 | `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
 | `recordIconCalls(worker)` | Record `chrome.action.setIcon` calls Chrome accepted. |
-| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves. |
+| `installWarnings(worker, manifest)` | Chrome's own install warnings for a manifest (`chrome.management.getPermissionWarningsByManifest`, no permission needed), from a loaded extension's worker. |
+| `warningsAddedBy(worker, manifest, names)` | `{warnings, without, added}`: the warnings with and without some permissions, and those only they bring (`withoutPermissions` is the pure part). |
+| `savedTabGroups(profile)` | Chrome's saved tab groups (`{title, pinned, urls}`) read from a closed profile's `Sync Data/LevelDB`: no extension API lists them. |
+| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves (a `#fragment` or `?query` ignored: `referencedPath`). |
 
 ## Stylesheet classes
 
@@ -186,9 +256,10 @@ except those listed, each with a reason:
 | Buttons (cr-button) | plain `<button>`; `.action` filled; `.link` as a link; `.icon-button` 32px round |
 | Settings menu | `.nav` > `ul.nav-list` > `a.nav-item[aria-current="page"]`, `.nav-separator` |
 | Manager layout | `.manager`/`.layout`, `.sidebar` with `.tree` > `.tree-item`, `.main` with `.list-card` |
-| Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` |
-| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` |
-| Toast (cr-toast) | `<div class="toast">text <button>Undo</button></div>` |
+| Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` (or `createMenu`) |
+| ⋮ icon | `<span class="icon icon-more-vert" aria-hidden="true">` (or `moreActionsButton`) |
+| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (one field: `askText`) |
+| Toast (cr-toast) | `<div class="toast">text <button>Undo</button></div>` (or `createToast`) |
 | Drawer (cr-drawer) | `<dialog class="drawer">` with `.drawer-head` and a `.nav` |
 | Side panel page | `<body class="side-panel">`: the panel's colours, a column 100vh high |
 | Panel tabs (cr-tabs) | `<div class="tabs" role="tablist">` of `button.tab[role="tab"][aria-selected]` |
@@ -206,7 +277,8 @@ chrome://bookmarks in Chromium 156 / Chrome 157; the sources are listed at the t
 
 ## Development
 
-`npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests, and the
+`npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests (the menu,
+the dialog and the Chrome readers in Playwright's Chromium, the rest in Node and jsdom), and the
 copied-code guard. The `.d.ts` files are generated from the JSDoc: `npm run types` writes them, and
 the type check fails while one is stale (it regenerates them into `.types/` and compares).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Shared pieces for Chrome extensions: Chrome's own page styles, a Chrome Sync settings store, the light/dark toolbar glyph, About links, and build and test helpers.",
   "type": "module",
   "main": "src/index.js",

package/src/build/vendor.js

@@ -19,7 +19,7 @@ import path from 'node:path';
 const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
 /** What a vendored copy holds, relative to `src/`: everything an extension page or worker may load. */
-export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'styles', 'toolbar']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'styles', 'toolbar', 'ui']);
 
 /** The kit's stylesheet, an absolute path in the installed package. */
 export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');

package/src/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * The kit's browser half: what an extension's pages, offscreen document and
- * service worker load. Every function takes the `chrome` APIs it uses as
- * arguments, so tests run the real logic against fakes.
+ * service worker load, Chrome's page components (the ⋮ menu, the one-field
+ * dialog, the toast with Undo) included. Every function takes the `chrome`
+ * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
  * in `@arraypress/extension-kit/testing`, and the stylesheet is
@@ -19,3 +20,22 @@ export { createSettingsStore } from './settings/store.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
 export { OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen, } from './toolbar/theme.js';
+export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { askText, checkText } from './ui/text-dialog.js';
+export { TOAST_MS, createToast } from './ui/toast.js';
+export type ActionMenu = import('./ui/menu.js').ActionMenu;
+export type MenuEntry = import('./ui/menu.js').MenuEntry;
+export type MenuItem = import('./ui/menu.js').MenuItem;
+export type MenuPlace = import('./ui/menu.js').MenuPlace;
+export type TextRequest = import('./ui/text-dialog.js').TextRequest;
+export type Toast = import('./ui/toast.js').Toast;
+/**
+ * The page helpers' types, for a page's JSDoc.
+ *
+ * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
+ * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
+ * @typedef {import('./ui/menu.js').MenuItem} MenuItem
+ * @typedef {import('./ui/menu.js').MenuPlace} MenuPlace
+ * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
+ * @typedef {import('./ui/toast.js').Toast} Toast
+ */

package/src/index.js

@@ -1,7 +1,8 @@
 /**
  * The kit's browser half: what an extension's pages, offscreen document and
- * service worker load. Every function takes the `chrome` APIs it uses as
- * arguments, so tests run the real logic against fakes.
+ * service worker load, Chrome's page components (the ⋮ menu, the one-field
+ * dialog, the toast with Undo) included. Every function takes the `chrome`
+ * APIs it uses as arguments, so tests run the real logic against fakes.
  *
  * Build-time helpers are in `@arraypress/extension-kit/build`, test helpers
  * in `@arraypress/extension-kit/testing`, and the stylesheet is
@@ -22,3 +23,17 @@ export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, scheme
 export {
   OFFSCREEN_PATH, TOOLBAR_ICON_DIR, createToolbarTheme, startToolbarTheme, toolbarIcon, watchFromOffscreen,
 } from './toolbar/theme.js';
+export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
+export { askText, checkText } from './ui/text-dialog.js';
+export { TOAST_MS, createToast } from './ui/toast.js';
+
+/**
+ * The page helpers' types, for a page's JSDoc.
+ *
+ * @typedef {import('./ui/menu.js').ActionMenu} ActionMenu
+ * @typedef {import('./ui/menu.js').MenuEntry} MenuEntry
+ * @typedef {import('./ui/menu.js').MenuItem} MenuItem
+ * @typedef {import('./ui/menu.js').MenuPlace} MenuPlace
+ * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
+ * @typedef {import('./ui/toast.js').Toast} Toast
+ */

package/src/styles/chrome-ui.css

@@ -136,9 +136,10 @@
     --tonal-text: rgb(4 30 73);
     --elevation-3: 0 1px 3px 0 rgb(60 64 67 / 0.3), 0 4px 8px 3px rgb(60 64 67 / 0.15);
 
-    /* Icons for link rows (cr:open-in-new, cr:arrow-right / subpage arrow). */
+    /* Icons for link rows (cr:open-in-new, cr:arrow-right / subpage arrow) and ⋮ buttons (cr:more-vert). */
     --icon-open-in-new: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M19 19H5V5h7V3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14c1.1 0 2-.9 2-2v-7h-2v7zM14 3v2h3.59l-9.83 9.83 1.41 1.41L19 6.41V10h2V3h-7z'/%3E%3C/svg%3E");
     --icon-arrow-right: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 6 8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z'/%3E%3C/svg%3E");
+    --icon-more-vert: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z'/%3E%3C/svg%3E");
 
     /* Sizes. */
     --radius: 8px;                         /* cards, fields, dialogs */
@@ -296,6 +297,9 @@ button.link:hover { background: none; text-decoration: underline; }
 
 .icon { width: 20px; height: 20px; fill: currentColor; flex: none; }
 
+/* The ⋮ icon without a sprite: <span class="icon icon-more-vert" aria-hidden="true">. */
+.icon-more-vert { display: inline-block; background: currentColor; mask: var(--icon-more-vert) center / contain no-repeat; }
+
 .sprite { position: absolute; width: 0; height: 0; overflow: hidden; }
 
 /* --------------------------------------------------------------- Fields */

package/src/testing/e2e.d.ts

@@ -26,10 +26,28 @@ export type LaunchedExtension = {
      */
     url: (page?: string) => string;
     /**
-     * Close the browser and delete its profile.
+     * The profile's folder (Chrome writes `DevToolsActivePort` there, for one).
+     */
+    profile: string;
+    /**
+     * Close the browser; from {@link launchExtension}, delete its profile too.
      */
     close: () => Promise<void>;
 };
+export type ExtensionProfile = {
+    /**
+     * The profile's folder.
+     */
+    dir: string;
+    /**
+     * Start the browser on it; its `close()` keeps the profile.
+     */
+    launch: () => Promise<LaunchedExtension>;
+    /**
+     * Delete the profile (close every launch first).
+     */
+    remove: () => Promise<void>;
+};
 export type LaunchOptions = NonNullable<Parameters<BrowserType['launchPersistentContext']>[1]> & {
     prefix?: string;
 };
@@ -42,7 +60,17 @@ export type LaunchOptions = NonNullable<Parameters<BrowserType['launchPersistent
  * @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.
+ * @property {string} profile The profile's folder (Chrome writes `DevToolsActivePort` there, for one).
+ * @property {() => Promise<void>} close Close the browser; from {@link launchExtension}, delete its profile too.
+ */
+/**
+ * A profile that outlives one browser start, for checks that something
+ * survives a restart (or that need a first start with a changed manifest).
+ *
+ * @typedef {object} ExtensionProfile
+ * @property {string} dir The profile's folder.
+ * @property {() => Promise<LaunchedExtension>} launch Start the browser on it; its `close()` keeps the profile.
+ * @property {() => Promise<void>} remove Delete the profile (close every launch first).
  */
 /**
  * What `launchExtension` takes: Playwright's persistent-context options, a
@@ -57,10 +85,31 @@ export type LaunchOptions = NonNullable<Parameters<BrowserType['launchPersistent
  * @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.
+ * @returns {Promise<Exclude<T, false | 0 | 0n | '' | null | undefined>>} The first truthy value
+ *   (typed without the falsy ones, so `until(() => ready && text, …)` is a string).
  * @throws {Error} "Timed out waiting for <what>".
  */
-export declare function until<T>(fn: () => T | Promise<T>, what: string, timeout?: number): Promise<NonNullable<T>>;
+export declare function until<T>(fn: () => T | Promise<T>, what: string, timeout?: number): Promise<Exclude<T, false | 0 | 0n | '' | null | undefined>>;
+/**
+ * A fresh profile for the unpacked extension at `dir`, to start the browser
+ * on as often as a test needs: each start loads the extension and waits 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<ExtensionProfile>} The profile.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const first = await profile.launch();
+ * await first.worker.evaluate(() => chrome.storage.local.set({seen: true}));
+ * await first.close();
+ * const { worker, close } = await profile.launch(); // the same storage, read as on any day
+ * await close();
+ * await profile.remove();
+ */
+export declare function extensionProfile(chromium: BrowserType, dir: string, { prefix, args, ...options }?: LaunchOptions): Promise<ExtensionProfile>;
 /**
  * Load the unpacked extension at `dir` into a fresh profile and wait for its
  * service worker.
@@ -69,13 +118,13 @@ export declare function until<T>(fn: () => T | Promise<T>, what: string, timeout
  * @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.
+ * @returns {Promise<LaunchedExtension>} The running extension; `close()` deletes the profile too.
  * @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>;
+export declare function launchExtension(chromium: BrowserType, dir: string, options?: LaunchOptions): Promise<LaunchedExtension>;
 /**
  * Emulate colour schemes in the offscreen document: one CDP session attached
  * to it, reused for every change.
@@ -99,6 +148,11 @@ export type CheckRunner = {
      * Run one check; resolves to whether it passed.
      */
     check: (name: string, fn: () => unknown) => Promise<boolean>;
+    /**
+     * Count a failure found outside any check (a page's
+     * uncaught error, say): printed now, listed and counted at the end.
+     */
+    fail: (name: string) => void;
     /**
      * Print the tally, and exit with 1 if anything failed.
      */
@@ -110,6 +164,8 @@ export type CheckRunner = {
  *
  * @typedef {object} CheckRunner
  * @property {(name: string, fn: () => unknown) => Promise<boolean>} check Run one check; resolves to whether it passed.
+ * @property {(name: string) => void} fail Count a failure found outside any check (a page's
+ *   uncaught error, say): printed now, listed and counted at the end.
  * @property {() => void} finish Print the tally, and exit with 1 if anything failed.
  */
 /**
@@ -118,7 +174,8 @@ export type CheckRunner = {
  *
  * @returns {CheckRunner} The runner.
  * @example
- * const { check, finish } = checkRunner();
+ * const { check, fail, finish } = checkRunner();
+ * page.on('pageerror', (error) => fail(`page error: ${error.message}`));
  * await check('the menu opens', async () => { … });
  * finish();
  */

package/src/testing/e2e.js

@@ -23,7 +23,18 @@ import path from 'node:path';
  * @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.
+ * @property {string} profile The profile's folder (Chrome writes `DevToolsActivePort` there, for one).
+ * @property {() => Promise<void>} close Close the browser; from {@link launchExtension}, delete its profile too.
+ */
+
+/**
+ * A profile that outlives one browser start, for checks that something
+ * survives a restart (or that need a first start with a changed manifest).
+ *
+ * @typedef {object} ExtensionProfile
+ * @property {string} dir The profile's folder.
+ * @property {() => Promise<LaunchedExtension>} launch Start the browser on it; its `close()` keeps the profile.
+ * @property {() => Promise<void>} remove Delete the profile (close every launch first).
  */
 
 /**
@@ -40,19 +51,65 @@ import path from 'node:path';
  * @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.
+ * @returns {Promise<Exclude<T, false | 0 | 0n | '' | null | undefined>>} The first truthy value
+ *   (typed without the falsy ones, so `until(() => ready && text, …)` is a string).
  * @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 (value) return /** @type {Exclude<T, false | 0 | 0n | '' | null | undefined>} */ (value);
     if (Date.now() > end) throw new Error(`Timed out waiting for ${what}`);
     await new Promise((resolve) => setTimeout(resolve, 50));
   }
 }
 
+/**
+ * A fresh profile for the unpacked extension at `dir`, to start the browser
+ * on as often as a test needs: each start loads the extension and waits 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<ExtensionProfile>} The profile.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const first = await profile.launch();
+ * await first.worker.evaluate(() => chrome.storage.local.set({seen: true}));
+ * await first.close();
+ * const { worker, close } = await profile.launch(); // the same storage, read as on any day
+ * await close();
+ * await profile.remove();
+ */
+export async function extensionProfile(chromium, dir, { prefix = 'extension-', args = [], ...options } = {}) {
+  const tmp = await mkdtemp(path.join(tmpdir(), prefix));
+  const profile = path.join(tmp, 'profile');
+  return {
+    dir: profile,
+    async launch() {
+      const context = await chromium.launchPersistentContext(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,
+        profile,
+        url: (page = '') => `chrome-extension://${extensionId}/${page}`,
+        close: () => context.close(),
+      };
+    },
+    remove: () => rm(tmp, { recursive: true, force: true }),
+  };
+}
+
 /**
  * Load the unpacked extension at `dir` into a fresh profile and wait for its
  * service worker.
@@ -61,29 +118,20 @@ export async function until(fn, what, timeout = 5000) {
  * @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.
+ * @returns {Promise<LaunchedExtension>} The running extension; `close()` deletes the profile too.
  * @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;
+export async function launchExtension(chromium, dir, options = {}) {
+  const profile = await extensionProfile(chromium, dir, options);
+  const launched = await profile.launch();
   return {
-    context,
-    worker,
-    extensionId,
-    url: (page = '') => `chrome-extension://${extensionId}/${page}`,
+    ...launched,
     async close() {
-      await context.close();
-      await rm(tmp, { recursive: true, force: true });
+      await launched.close();
+      await profile.remove();
     },
   };
 }
@@ -139,6 +187,8 @@ export async function recordIconCalls(worker) {
  *
  * @typedef {object} CheckRunner
  * @property {(name: string, fn: () => unknown) => Promise<boolean>} check Run one check; resolves to whether it passed.
+ * @property {(name: string) => void} fail Count a failure found outside any check (a page's
+ *   uncaught error, say): printed now, listed and counted at the end.
  * @property {() => void} finish Print the tally, and exit with 1 if anything failed.
  */
 
@@ -148,7 +198,8 @@ export async function recordIconCalls(worker) {
  *
  * @returns {CheckRunner} The runner.
  * @example
- * const { check, finish } = checkRunner();
+ * const { check, fail, finish } = checkRunner();
+ * page.on('pageerror', (error) => fail(`page error: ${error.message}`));
  * await check('the menu opens', async () => { … });
  * finish();
  */
@@ -169,6 +220,10 @@ export function checkRunner() {
         return false;
       }
     },
+    fail(name) {
+      failures.push(name);
+      console.log(`  ✗ ${name}`);
+    },
     finish() {
       console.log(`\n${passed} passed, ${failures.length} failed`);
       if (!failures.length) return;

package/src/testing/index.d.ts

@@ -1,9 +1,35 @@
 /**
  * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
- * end-to-end tests, and checks for a packaging test. Node only.
+ * end-to-end tests and a server for their pages, Chrome's install warnings
+ * and saved tab groups, and checks for a packaging test. Node only.
  *
  * @module testing
  */
-export { checkRunner, checkToolbarTheme, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
-export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';
+export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
+export { savedTabGroups } from './saved-groups.js';
+export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
+export type CheckRunner = import('./e2e.js').CheckRunner;
+export type ExtensionProfile = import('./e2e.js').ExtensionProfile;
+export type LaunchedExtension = import('./e2e.js').LaunchedExtension;
+export type LaunchOptions = import('./e2e.js').LaunchOptions;
+export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
+export type Manifest = import('./warnings.js').Manifest;
+export type Reply = import('./server.js').Reply;
+export type Routes = import('./server.js').Routes;
+export type TestServer = import('./server.js').TestServer;
+/**
+ * The helpers' types, for a test's JSDoc.
+ *
+ * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
+ * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
+ * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
+ * @typedef {import('./warnings.js').Manifest} Manifest
+ * @typedef {import('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */

package/src/testing/index.js

@@ -1,10 +1,28 @@
 /**
  * The kit's test helpers: a fake `chrome.storage`, Playwright helpers for
- * end-to-end tests, and checks for a packaging test. Node only.
+ * end-to-end tests and a server for their pages, Chrome's install warnings
+ * and saved tab groups, and checks for a packaging test. Node only.
  *
  * @module testing
  */
 
-export { checkRunner, checkToolbarTheme, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until } from './e2e.js';
+export { serve } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
-export { filesUnder, manifestReferences, missingReferences, zipEntries } from './package.js';
+export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
+export { savedTabGroups } from './saved-groups.js';
+export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings.js';
+
+/**
+ * The helpers' types, for a test's JSDoc.
+ *
+ * @typedef {import('./e2e.js').CheckRunner} CheckRunner
+ * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
+ * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
+ * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
+ * @typedef {import('./warnings.js').Manifest} Manifest
+ * @typedef {import('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */