@arraypress/extension-kit 1.4.0 → 1.6.0

package/README.md

@@ -10,8 +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"), the toast with Undo and a settings card's site list, built on the
+- **Chrome's page components**: the ⋮ action menu and its row button, the text dialog
+  ("Rename folder", or several fields as "Add site search"), the toast with Undo and a settings card's site list, built on the
   stylesheet's classes; they work in a content script's shadow root too.
 - **Sites**: what people type into a per-site list, and whether a page is on one.
 - **Build and test helpers** (Node): icon rendering, vendoring npm packages (with a staleness
@@ -193,6 +193,24 @@ withSite(['a.com', 'b.com'], 'a.com');       // ['b.com', 'a.com'], what a list
 A site is http or https with a dot in its host (or `localhost`); text without a scheme is https;
 `localhost:8080` is a host and port. Pure, so a content script can load `sites/sites.js` alone.
 
+## A content script on every site
+
+```js
+// The content script runs everywhere only while the optional all-sites grant is held, less the
+// "Never on" sites; one call brings the registration in line, whatever changed.
+const sync = contentScriptSync(chrome.scripting, 'prices', async () => {
+  const settings = await store.load(chrome.storage);
+  if (!settings.everySite || !(await chrome.permissions.contains({ origins: ALL_SITES }))) return null;
+  return { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: settings.neverSites.flatMap(hostPatterns), runAt: 'document_idle' };
+});
+chrome.permissions.onAdded.addListener(() => sync());
+chrome.permissions.onRemoved.addListener(() => sync()); // site access taken back on chrome://extensions
+```
+
+Registers, updates or unregisters the script `id` to match what `want()` gives at the time (null:
+none). Calls run one after another, so a quick run of changes can't register twice or end out of
+order; a refused change rejects that call only.
+
 ## Time limits
 
 ```js
@@ -203,6 +221,13 @@ const groups = await within(chrome.tabGroups.query({}), 2000, []); // a Chrome c
 rejects; its timer cleared once the work settles (the work itself isn't stopped). In the runtime
 half, so a service worker or page can use it; the test helpers use it too.
 
+```js
+await eachLimited(files, 4, async (file) => save(file)); // at most four at once
+```
+
+`eachLimited(items, limit, work)`: `work(item, slot, index)` on every item, at most `limit` at once;
+in the runtime half too (`/testing` exports it as well).
+
 ## Page components
 
 Chrome's own components, made in the page by script (no markup to copy), styled by `chrome-ui.css`.
@@ -238,7 +263,7 @@ opens it below the button instead. `menuPosition` and `isInside` are the pure ge
 `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)
+### Text dialog (cr-dialog)
 
 ```js
 const name = await askText({ title: 'Rename workspace', label: 'Name', value: workspace.name, maxLength: 200 });
@@ -254,6 +279,26 @@ disabled while the text is blank or `validate` gives a reason, which shows under
 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.
 
+### Dialog with several fields
+
+```js
+const rule = await askFields({
+  title: 'Add folder rule', action: 'Add',
+  fields: [
+    { name: 'from', label: 'Downloads from', placeholder: 'example.com or .pdf', validate: checkFrom },
+    { name: 'folder', label: 'Folder', value: 'Receipts' },
+  ],
+});
+if (rule) addRule(rule.from, rule.folder);
+```
+
+The same dialog as chrome://settings/searchEngines asks for a site search: a field each, in
+order. Resolves to each field's text by its `name`, trimmed, or `null` when cancelled. The action
+button stays disabled until every field is filled in and valid, each field's reason under it; the
+focus starts in the first empty field. `askText` is this with one field. A one-field dialog's ids
+are `text-dialog-input` and `text-dialog-error`; with several, `text-dialog-<name>` and
+`text-dialog-<name>-error` (`fieldIds`), for a test to find them.
+
 ### Toast with Undo (cr-toast)
 
 ```js
@@ -346,19 +391,22 @@ except those listed, each with a reason:
 |---|---|
 | `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), profile, close()}`. |
+| `launchDownloading(chromium, dir, options)`, `filesIn(dir)` | An extension in a browser that downloads for real: `{…launchExtension's, downloads}`, the profile's own Downloads folder (Playwright otherwise saves downloads under made-up names no extension sees); the files under a folder, downloads still running left out. |
 | `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({timeout})` | Named checks that report and go on: `check(name, fn, {timeout})`, `fail(name)` for an error found outside a check, `finish()`. A check that runs past its limit (`CHECK_MS`, 60 s) fails, and the run goes on. |
-| `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)`. |
+| `eachLimited(items, limit, work)` | Work through a list at most `limit` at once, `work(item, slot, index)` (also in the main entry). |
 | `realisticBrowser(options)`, `chromeUserAgent(browser)` | Launch options and a user agent for a browser that doesn't say it's automated, for live checks. |
 | `closeOnSignal(close)` | On Ctrl-C or a kill, close the run's browsers, then exit. |
 | `testBuildDir(root, name)` | As in `/build`, for the tests that load the build. |
-| `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()}`. |
+| `serve(routes, {port, tls})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. With `tls` (`testCertificate()`, a throwaway one from `openssl`), over HTTPS: for a site Chrome reaches only over HTTPS, mapped with `--host-resolver-rules`, Chromium started with `--ignore-certificate-errors`. |
 | `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. |
 | `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. |
+| `parseLiveOptions(argv, env, {usage})`, `parseProxy(address)` | A live checker's command line (`--only`, `--category`, `--concurrency`, `--proxy` or `HTTPS_PROXY`, `--locale`, `--timezone`, `--out`, `--help`), and a proxy address for Playwright with its password hidden for the output. |
+| `exitPoint(request)` | Where the run's traffic leaves for the internet (`{ip, country, where, source}`), from a keyless lookup service through the context's proxy: sites decide what to show by it. |
 | `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
@@ -387,7 +435,7 @@ except those listed, each with a reason:
 | 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` (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`) |
+| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` (`askText`, `askFields`) |
 | Toast (cr-toast) | `<div class="toast" popover="manual">text <button>Undo</button></div>` (or `createToast`); with `hidden` instead of `popover`, it shows over the page but not the top layer |
 | 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "1.4.0",
+  "version": "1.6.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

@@ -28,7 +28,7 @@ const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const KIT = '@arraypress/extension-kit';
 
 /** What a vendored copy of the kit 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', 'sites', 'styles', 'time', 'toolbar', 'ui']);
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'scripting', 'settings', 'sites', 'styles', 'time', '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

@@ -17,33 +17,41 @@ export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
+export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export { MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite, } from './sites/sites.js';
+export { eachLimited } from './time/pool.js';
 export { within } from './time/time.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 { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
-export { askText, checkText } from './ui/text-dialog.js';
+export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
+export type ContentScript = import('./scripting/registration.js').ContentScript;
 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 SiteList = import('./ui/site-list.js').SiteList;
+export type FieldRequest = import('./ui/text-dialog.js').FieldRequest;
+export type FieldsRequest = import('./ui/text-dialog.js').FieldsRequest;
 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('./scripting/registration.js').ContentScript} ContentScript
  * @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/site-list.js').SiteList} SiteList
+ * @typedef {import('./ui/text-dialog.js').FieldRequest} FieldRequest
+ * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/index.js

@@ -18,12 +18,14 @@ export { focusedElement } from './dom/focus.js';
 export { localize, translator } from './dom/i18n.js';
 export { byId, setAboutLinks, statusFlasher, valueRow } from './dom/page.js';
 export { setUpPage } from './dom/setup.js';
+export { contentScriptSync } from './scripting/registration.js';
 export { createSettingsSaver } from './settings/saver.js';
 export { MAX_SYNC_ITEM_BYTES } from './settings/storage.js';
 export { createSettingsStore } from './settings/store.js';
 export {
   MAX_HOST_LENGTH, hostPatterns, onSite, originPattern, siteHost, siteLabel, siteOrigin, withSite, withSiteReplaced, withoutSite,
 } from './sites/sites.js';
+export { eachLimited } from './time/pool.js';
 export { within } from './time/time.js';
 export { POLL_MS, watchSchemeOffscreen } from './toolbar/offscreen.js';
 export { DARK_QUERY, TOOLBAR_DARK_KEY, TOOLBAR_SCHEME, reportColorScheme, schemeSender, watchColorScheme } from './toolbar/scheme.js';
@@ -32,17 +34,20 @@ export {
 } from './toolbar/theme.js';
 export { MENU_EDGE, createMenu, isInside, menuPosition, moreActionsButton } from './ui/menu.js';
 export { SITE_LIST_MESSAGES, SITE_LIST_WORDS, createSiteList } from './ui/site-list.js';
-export { askText, checkText } from './ui/text-dialog.js';
+export { askFields, askText, checkText, fieldIds } from './ui/text-dialog.js';
 export { TOAST_MS, createToast } from './ui/toast.js';
 
 /**
  * The page helpers' types, for a page's JSDoc.
  *
+ * @typedef {import('./scripting/registration.js').ContentScript} ContentScript
  * @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/site-list.js').SiteList} SiteList
+ * @typedef {import('./ui/text-dialog.js').FieldRequest} FieldRequest
+ * @typedef {import('./ui/text-dialog.js').FieldsRequest} FieldsRequest
  * @typedef {import('./ui/text-dialog.js').TextRequest} TextRequest
  * @typedef {import('./ui/toast.js').Toast} Toast
  */

package/src/scripting/registration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One registered content script kept in step with what may run: registered,
+ * updated or unregistered to match, each change after the last, so a quick
+ * run of setting and permission changes can't register and unregister out
+ * of order. For an extension whose content script runs on every site only
+ * while an optional all-sites grant is held, less a "Never on" list.
+ *
+ * @module scripting/registration
+ */
+export type ContentScript = Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {
+    js: string[];
+};
+export type Scripting = Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>;
+/** @typedef {Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {js: string[]}} ContentScript The script, but its id: its `js`, `matches` and the rest. */
+/**
+ * The parts of `chrome.scripting` a registration uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>} Scripting
+ */
+/**
+ * Keep the content script `id` registered as `want()` says: the script, or
+ * null for none. Each call asks `want()` afresh once the change before it is
+ * done, so the last call always wins.
+ *
+ * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {string} id - The registered script's id.
+ * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
+ *   grants read at the time).
+ * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
+ * @example
+ * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })
+ *   ? { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: neverSites.flatMap(hostPatterns), runAt: 'document_idle' }
+ *   : null));
+ * chrome.permissions.onAdded.addListener(() => sync());
+ */
+export declare function contentScriptSync(scripting: Scripting, id: string, want: () => Promise<ContentScript | null>): () => Promise<void>;

package/src/scripting/registration.js

@@ -0,0 +1,54 @@
+/**
+ * One registered content script kept in step with what may run: registered,
+ * updated or unregistered to match, each change after the last, so a quick
+ * run of setting and permission changes can't register and unregister out
+ * of order. For an extension whose content script runs on every site only
+ * while an optional all-sites grant is held, less a "Never on" list.
+ *
+ * @module scripting/registration
+ */
+
+/** @typedef {Omit<chrome.scripting.RegisteredContentScript, 'id' | 'js'> & {js: string[]}} ContentScript The script, but its id: its `js`, `matches` and the rest. */
+
+/**
+ * The parts of `chrome.scripting` a registration uses.
+ *
+ * @typedef {Pick<typeof chrome.scripting, 'getRegisteredContentScripts' | 'registerContentScripts' | 'updateContentScripts' | 'unregisterContentScripts'>} Scripting
+ */
+
+/**
+ * Keep the content script `id` registered as `want()` says: the script, or
+ * null for none. Each call asks `want()` afresh once the change before it is
+ * done, so the last call always wins.
+ *
+ * @param {Scripting} scripting - `chrome.scripting` (or a fake in tests).
+ * @param {string} id - The registered script's id.
+ * @param {() => Promise<ContentScript | null>} want - What should be registered now (settings and
+ *   grants read at the time).
+ * @returns {() => Promise<void>} Makes the registration match; rejects if Chrome refuses.
+ * @example
+ * const sync = contentScriptSync(chrome.scripting, 'prices', async () => (await chrome.permissions.contains({ origins: ALL_SITES })
+ *   ? { js: ['content/loader.js'], matches: ALL_SITES, excludeMatches: neverSites.flatMap(hostPatterns), runAt: 'document_idle' }
+ *   : null));
+ * chrome.permissions.onAdded.addListener(() => sync());
+ */
+export function contentScriptSync(scripting, id, want) {
+  /** The last change, so the next waits for it. */
+  let queue = Promise.resolve();
+  const apply = async () => {
+    const script = await want();
+    const registered = (await scripting.getRegisteredContentScripts({ ids: [id] })).length > 0;
+    if (!script) {
+      if (registered) await scripting.unregisterContentScripts({ ids: [id] });
+      return;
+    }
+    const full = { ...script, id };
+    if (registered) await scripting.updateContentScripts([full]);
+    else await scripting.registerContentScripts([full]);
+  };
+  return () => {
+    const run = queue.then(apply, apply);
+    queue = run.catch(() => {});
+    return run;
+  };
+}

package/src/testing/downloads.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A browser that downloads for real, for an extension that names, files or
+ * makes downloads. Playwright normally takes downloads over (CDP's
+ * `Browser.setDownloadBehavior` set to `allowAndName`), saving them under
+ * made-up names where no extension sees them: `downloads.onDeterminingFilename`
+ * never fires, and `chrome.downloads.download`'s names are lost. So the
+ * profile gets its own Downloads folder (Chrome's `download.default_directory`
+ * preference, written before the first start) and the behaviour goes back to
+ * Chrome's default: files land on disk as on a person's computer.
+ *
+ * @module testing/downloads
+ */
+import type { BrowserType } from 'playwright';
+import type { LaunchOptions, LaunchedExtension } from './e2e.js';
+/** @import { BrowserType } from 'playwright' */
+/** @import { LaunchOptions, LaunchedExtension } from './e2e.js' */
+/**
+ * Every file under a folder, as paths from it (Chrome's `.crdownload` files
+ * of downloads still running left out), sorted.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} The files.
+ * @example
+ * await filesIn(downloads); // ['Trips/Lake.jpg', 'Trips/Lake 2.jpg']
+ */
+export declare function filesIn(dir: string): Promise<string[]>;
+/**
+ * Load the unpacked extension at `dir` into a fresh profile whose downloads
+ * go to a folder of their own, really.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - As `launchExtension`'s.
+ * @returns {Promise<LaunchedExtension & {downloads: string}>} The running extension, and its
+ *   Downloads folder; `close()` deletes both.
+ * @example
+ * const { context, downloads, close } = await launchDownloading(chromium, 'extension');
+ */
+export declare function launchDownloading(chromium: BrowserType, dir: string, options?: LaunchOptions): Promise<LaunchedExtension & {
+    downloads: string;
+}>;

package/src/testing/downloads.js

@@ -0,0 +1,70 @@
+/**
+ * A browser that downloads for real, for an extension that names, files or
+ * makes downloads. Playwright normally takes downloads over (CDP's
+ * `Browser.setDownloadBehavior` set to `allowAndName`), saving them under
+ * made-up names where no extension sees them: `downloads.onDeterminingFilename`
+ * never fires, and `chrome.downloads.download`'s names are lost. So the
+ * profile gets its own Downloads folder (Chrome's `download.default_directory`
+ * preference, written before the first start) and the behaviour goes back to
+ * Chrome's default: files land on disk as on a person's computer.
+ *
+ * @module testing/downloads
+ */
+
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { extensionProfile } from './e2e.js';
+
+/** @import { BrowserType } from 'playwright' */
+/** @import { LaunchOptions, LaunchedExtension } from './e2e.js' */
+
+/**
+ * Every file under a folder, as paths from it (Chrome's `.crdownload` files
+ * of downloads still running left out), sorted.
+ *
+ * @param {string} dir - The folder.
+ * @returns {Promise<string[]>} The files.
+ * @example
+ * await filesIn(downloads); // ['Trips/Lake.jpg', 'Trips/Lake 2.jpg']
+ */
+export async function filesIn(dir) {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && !entry.name.endsWith('.crdownload'))
+    .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name))).sort();
+}
+
+/**
+ * Load the unpacked extension at `dir` into a fresh profile whose downloads
+ * go to a folder of their own, really.
+ *
+ * @param {BrowserType} chromium - Playwright's `chromium`.
+ * @param {string} dir - The unpacked extension.
+ * @param {LaunchOptions} [options] - As `launchExtension`'s.
+ * @returns {Promise<LaunchedExtension & {downloads: string}>} The running extension, and its
+ *   Downloads folder; `close()` deletes both.
+ * @example
+ * const { context, downloads, close } = await launchDownloading(chromium, 'extension');
+ */
+export async function launchDownloading(chromium, dir, options = {}) {
+  const profile = await extensionProfile(chromium, dir, options);
+  const downloads = path.join(path.dirname(profile.dir), 'Downloads');
+  await mkdir(path.join(profile.dir, 'Default'), { recursive: true });
+  await mkdir(downloads, { recursive: true });
+  await writeFile(path.join(profile.dir, 'Default', 'Preferences'), JSON.stringify({
+    download: { default_directory: downloads, prompt_for_download: false, directory_upgrade: true },
+  }));
+  const launched = await profile.launch();
+  const page = await launched.context.newPage();
+  const cdp = await launched.context.newCDPSession(page);
+  await cdp.send('Browser.setDownloadBehavior', { behavior: 'default' });
+  await cdp.detach();
+  await page.close();
+  return {
+    ...launched,
+    downloads,
+    async close() {
+      await launched.close();
+      await profile.remove();
+    },
+  };
+}

package/src/testing/index.d.ts

@@ -9,8 +9,10 @@
 export { TEST_BUILDS_ENV, testBuildDir } from '../build/test-build.js';
 export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export { CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until, } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { serve, testCertificate } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
@@ -19,6 +21,8 @@ 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 Exit = import('./live.js').Exit;
+export type LiveOptions = import('./live.js').LiveOptions;
 export type SavedTabGroup = import('./saved-groups.js').SavedTabGroup;
 export type Manifest = import('./warnings.js').Manifest;
 export type Reply = import('./server.js').Reply;
@@ -31,6 +35,8 @@ export type TestServer = import('./server.js').TestServer;
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/index.js

@@ -12,8 +12,10 @@ export { chromeUserAgent, closeOnSignal, realisticBrowser } from './browser.js';
 export {
   CHECK_MS, checkRunner, checkToolbarTheme, extensionProfile, launchExtension, offscreenEmulator, recordIconCalls, until,
 } from './e2e.js';
-export { eachLimited } from './pool.js';
-export { serve } from './server.js';
+export { exitPoint, parseLiveOptions, parseProxy } from './live.js';
+export { eachLimited } from '../time/pool.js';
+export { filesIn, launchDownloading } from './downloads.js';
+export { serve, testCertificate } from './server.js';
 export { SYNC_WRITES_PER_MINUTE, fakeChromeStorage } from './fake-storage.js';
 export { filesUnder, manifestReferences, missingReferences, referencedPath, zipEntries } from './package.js';
 export { savedTabGroups } from './saved-groups.js';
@@ -26,6 +28,8 @@ export { installWarnings, warningsAddedBy, withoutPermissions } from './warnings
  * @typedef {import('./e2e.js').ExtensionProfile} ExtensionProfile
  * @typedef {import('./e2e.js').LaunchedExtension} LaunchedExtension
  * @typedef {import('./e2e.js').LaunchOptions} LaunchOptions
+ * @typedef {import('./live.js').Exit} Exit
+ * @typedef {import('./live.js').LiveOptions} LiveOptions
  * @typedef {import('./saved-groups.js').SavedTabGroup} SavedTabGroup
  * @typedef {import('./warnings.js').Manifest} Manifest
  * @typedef {import('./server.js').Reply} Reply

package/src/testing/live.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What a live checker (a run over real sites, never in CI) shares: its
+ * command line (which sites, how many at once, a proxy, how the browser
+ * looks) and where its traffic leaves for the internet, which decides what
+ * many sites show (cookie banners, prices, currency).
+ *
+ * @module testing/live
+ */
+import type { APIRequestContext } from 'playwright';
+export type Proxy = {
+    /**
+     * e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+     */
+    server: string;
+    /**
+     * From the address, if it has one.
+     */
+    username?: string;
+    /**
+     * From the address, if it has one.
+     */
+    password?: string;
+};
+export type LiveOptions = {
+    /**
+     * Only sites whose address or name contains one of these (any case).
+     */
+    only: string[];
+    /**
+     * Only these categories (by id).
+     */
+    categories: string[];
+    /**
+     * Sites checked at once.
+     */
+    concurrency: number;
+    /**
+     * The proxy every request goes through.
+     */
+    proxy: Proxy | null;
+    /**
+     * The proxy's address without its password, for the output.
+     */
+    proxyLabel: string;
+    /**
+     * The browser's language (navigator.language, Accept-Language).
+     */
+    locale: string;
+    /**
+     * The browser's time zone.
+     */
+    timezone: string;
+    /**
+     * Where the report goes ('' for the checker's default).
+     */
+    out: string;
+    /**
+     * Show the usage and stop.
+     */
+    help: boolean;
+};
+/** @import { APIRequestContext } from 'playwright' */
+/**
+ * A proxy, as Playwright takes it.
+ *
+ * @typedef {object} Proxy
+ * @property {string} server e.g. "http://uk.example.net:8080" or "socks5://127.0.0.1:1080".
+ * @property {string} [username] From the address, if it has one.
+ * @property {string} [password] From the address, if it has one.
+ */
+/**
+ * A live checker's options.
+ *
+ * @typedef {object} LiveOptions
+ * @property {string[]} only Only sites whose address or name contains one of these (any case).
+ * @property {string[]} categories Only these categories (by id).
+ * @property {number} concurrency Sites checked at once.
+ * @property {Proxy | null} proxy The proxy every request goes through.
+ * @property {string} proxyLabel The proxy's address without its password, for the output.
+ * @property {string} locale The browser's language (navigator.language, Accept-Language).
+ * @property {string} timezone The browser's time zone.
+ * @property {string} out Where the report goes ('' for the checker's default).
+ * @property {boolean} help Show the usage and stop.
+ */
+/**
+ * Read a proxy address.
+ *
+ * @param {string} address - e.g. "http://user:pass@host:3128".
+ * @returns {{ proxy: Proxy, label: string }} For Playwright, and for the output (no password).
+ * @throws {Error} When it isn't an address.
+ * @example
+ * parseProxy('http://me:secret@uk.example:8080').label; // 'http://me:•••@uk.example:8080'
+ */
+export declare function parseProxy(address: string): {
+    proxy: Proxy;
+    label: string;
+};
+/**
+ * Read a live checker's command line: `--only <word>` (repeatable, or bare
+ * words), `--category <id>` (repeatable), `--concurrency <n>`, `--proxy <url>`
+ * (default `HTTPS_PROXY`), `--locale <tag>`, `--timezone <zone>`, `--out <dir>`,
+ * `--help`. A value may follow an `=` ("--only=amazon"); commas list several.
+ *
+ * @param {readonly string[]} argv - The arguments after the script.
+ * @param {Readonly<Record<string, string | undefined>>} env - The environment (HTTPS_PROXY, https_proxy).
+ * @param {{ usage: string, concurrency?: number, maxConcurrency?: number, locale?: string, timezone?: string }} defaults - The
+ *   usage text (shown with an unknown option), and the defaults: 3 at once (at most 8), en-GB, Europe/London.
+ * @returns {LiveOptions} The options.
+ * @throws {Error} On an unknown option or a bad value.
+ * @example
+ * parseLiveOptions(['--category', 'shops', 'amazon'], {}, { usage }).only; // ['amazon']
+ */
+export declare function parseLiveOptions(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, { usage, concurrency, maxConcurrency, locale, timezone }: {
+    usage: string;
+    concurrency?: number;
+    maxConcurrency?: number;
+    locale?: string;
+    timezone?: string;
+}): LiveOptions;
+export type Exit = {
+    /**
+     * The public address.
+     */
+    ip: string;
+    /**
+     * Its ISO country code ("GB", "TH").
+     */
+    country: string;
+    /**
+     * Readable: city and organisation, where the service says.
+     */
+    where: string;
+    /**
+     * The service that answered.
+     */
+    source: string;
+};
+/**
+ * Where the browser's traffic leaves for the internet: its public IP's
+ * country, asked once through the same proxy the browser uses. Sites go by
+ * that address, not the browser's language or time zone.
+ *
+ * @param {APIRequestContext} request - A browser context's `request` (it uses the context's proxy).
+ * @returns {Promise<Exit | null>} null when no service answered.
+ */
+export declare function exitPoint(request: APIRequestContext): Promise<Exit | null>;