@arraypress/extension-kit 1.0.0 → 1.1.0

package/README.md

@@ -157,7 +157,10 @@ 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.0.0",
+  "version": "1.1.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/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,29 @@
 /**
  * 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, 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 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 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('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */

package/src/testing/index.js

@@ -1,10 +1,24 @@
 /**
  * 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, 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';
+
+/**
+ * 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('./server.js').Reply} Reply
+ * @typedef {import('./server.js').Routes} Routes
+ * @typedef {import('./server.js').TestServer} TestServer
+ */

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