@itmetsam/samurai-framework 0.7.1 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Samurai
 
-A browser test framework written in TypeScript. It drives a real browser over the [WebDriver BiDi](https://www.w3.org/TR/webdriver-bidi/) protocol, with no WebDriver server and no Playwright or Puppeteer underneath.
+A browser test framework written in TypeScript. It drives a real browser over the [WebDriver BiDi](https://www.w3.org/TR/webdriver-bidi/) protocol, with no Playwright or Puppeteer underneath. Firefox speaks BiDi itself; Chrome is driven through its own `chromedriver`, which the framework starts for you.
 
 [![CI](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml)
 
@@ -20,16 +20,32 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
+- **Flows.** Chain tests and groups into a graph with conditions, variables, waits and HTTP requests, and run it from the command line or CI (see [Flows](docs/flows.md)).
 - **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](docs/recorder.md)). The Electron app that ties them together lives in a separate repository (see the [roadmap](docs/roadmap.md)).
 
 > **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
 
 ## Getting started
 
+### In your own project
+
+The package is published on npm as [`@itmetsam/samurai-framework`](https://www.npmjs.com/package/@itmetsam/samurai-framework). In an empty folder:
+
+```sh
+npx -p @itmetsam/samurai-framework samurai init   # config, an example test, .env.example, .gitignore
+npm install
+npx samurai browsers install firefox             # once per machine
+npx samurai run
+```
+
+Specs and the config then import from `@itmetsam/samurai-framework` instead of the relative paths used below. See [Command line](docs/cli.md).
+
+The rest of this section works in a checkout of this repository.
+
 ### 1. Requirements
 
-- [Node.js](https://nodejs.org) 26 or newer and [Bun](https://bun.sh) 1.3 or newer (CI uses these versions)
-- Firefox, downloaded by the framework: run `npx samurai browsers install firefox` once in a project (`bun run dev browsers install firefox` in this checkout; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
+- [Node.js](https://nodejs.org) 24 or newer (`engines` in `package.json`; CI uses 26) and, to work on the framework, [Bun](https://bun.sh) 1.3 or newer
+- Firefox, downloaded by the framework: run `bun run dev browsers install firefox` once in this checkout (`npx samurai browsers install firefox` in a project; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
 
 ### 2. Install
 
@@ -86,9 +102,9 @@ bun run dev --env production   # another environment (or SAMURAI_ENV=production)
 bun run dev --timeout 60000    # per-test timeout in ms; also --expect-timeout
 ```
 
-Once the package is installed in a project, `samurai run` does the same with a readable summary and a proper exit code, and `samurai init` scaffolds a new project (see [Command line](docs/cli.md)).
+`bun run dev` is `samurai run` straight from the sources, so it takes the same options (`--grep`, `--file`, `--group`, `--headless`, `--json`, …) and the other commands too (`bun run dev list`, `bun run dev browsers install firefox`). See [Command line](docs/cli.md).
 
-A browser window opens for each test and closes when the test ends. The result is written to `result/report.json` (status, duration and error per test); nothing summarises it on the console yet. The process exits with code 0 when every test passed and 1 otherwise (`--headless` hides the window; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Framework logs go to the console and `logs/`.
+A browser window opens for each test and closes when the test ends (`--headless` hides it; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Each test's result is printed as it finishes, followed by a summary, and the full report is written to `result/report.json`. The process exits with code 0 when every test passed, 1 otherwise and 2 for a usage or configuration error. Framework logs go to stderr and `logs/`.
 
 > `src/tests/index.spec.ts` is an example that submits a real contact form. Delete it or replace it before running everything.
 
@@ -100,6 +116,7 @@ A project can also keep flows in `flows/*.flow.json` (edited in the Samurai app)
 
 ```sh
 cp .env.example .env.staging
+# then add a line per secret, e.g.
 # SAMURAI_SECRET_TEST_PASSWORD=...
 ```
 
@@ -118,19 +135,21 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Environments and secrets](docs/environments-and-secrets.md) | Per-environment settings, variables, secrets and masking                                              |
 | [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
 | [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
+| [Writing a step](docs/steps.md)                              | `defineStep`: flow steps of your own, the built-in steps                                              |
 | [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
 | [Steps and the recorder](docs/recorder.md)                   | The step codec, the recording engine and the recorder toolbar                                         |
 | [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
 | [Contributing](docs/contributing.md)                         | Project layout, running the framework's own tests, conventions                                        |
 | [Roadmap](docs/roadmap.md)                                   | What is built and what is still open                                                                  |
 
-Design notes for every feature live in [`docs/superpowers/specs`](docs/superpowers/specs).
+The [documentation index](docs/README.md) lists every guide and design note by topic. Design notes for every feature live in [`docs/superpowers/specs`](docs/superpowers/specs).
 
 ## Scripts
 
-| Command                | Does                                            |
-| ---------------------- | ----------------------------------------------- |
-| `bun run dev`          | Runs the test suite (`tsx src/index.ts`)        |
-| `bun run test`         | Unit tests of the framework (no browser needed) |
-| `bun run test:browser` | Browser tests of the framework (needs Firefox)  |
-| `bun run build`        | Typechecks and compiles to `dist/`              |
+| Command                | Does                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `bun run dev`          | `samurai` from the sources (`tsx src/index.ts`)                                                                     |
+| `bun run test`         | Unit tests of the framework (no browser needed)                                                                     |
+| `bun run test:browser` | Browser tests of the framework (Firefox; `SAMURAI_TEST_BROWSER=chrome` or `bun run test:browser:chrome` for Chrome) |
+| `bun run test:cli`     | Tests of the `samurai` command (build first)                                                                        |
+| `bun run build`        | Typechecks and compiles to `dist/`                                                                                  |

package/dist/api.d.ts

@@ -3,3 +3,4 @@ export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
 export type { TestFixtures } from "./types/test.js";
+export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/api.js

@@ -2,3 +2,4 @@ export { test, describe } from "./runner/registry.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, } from "./flows/steps/index.js";
+export { generatedFile, } from "./browser/generated-files.js";

package/dist/browser/browser-finder.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import logger from "../logger/index.js";
 const supportedBrowsers = ["firefox"];
 const macBrowserPaths = {
-    // chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
     firefox: "/Applications/Firefox.app/Contents/MacOS/Firefox",
 };
 /** @deprecated Launches use the builds SAMURAI downloads (`samurai browsers install`); removed in a later major */
@@ -82,7 +82,7 @@ function findBrowserMac(browserName) {
     return checkPathExists(macBrowserPaths[browserName]);
 }
 const linuxBinaryNames = {
-    // chrome: "google-chrome",
+    chrome: "google-chrome",
     firefox: "firefox",
 };
 function findBrowserLinux(browserName) {

package/dist/browser/browser.d.ts

@@ -1,23 +1,15 @@
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { SupportedBrowser } from "../types/browser.js";
 import { BiDiConnector } from "../transport/bidi-connection.js";
 import Page from "./page.js";
+import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+import { type BrowserProcess } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import type { UserPromptHandler } from "../types/bidi-modules/session.js";
 import { type EmulationOptions } from "./emulation.js";
+import { ChromeDownloadFolders } from "./download-folders.js";
 import type { BiDiCommands } from "../types/bidi.js";
 import type { CookieFilter, PartialCookie, PartitionDescriptor } from "../types/bidi-modules/storage.js";
-/**
- * Sent with session.new. With "ignore" the browser leaves a JavaScript dialog open and reports it
- * (`browsingContext.userPromptOpened`), so the framework decides how to answer instead of the browser.
- */
-export declare const SESSION_CAPABILITIES: {
-    alwaysMatch: {
-        unhandledPromptBehavior: {
-            default: string;
-        };
-    };
-};
+export { SESSION_CAPABILITIES };
 /** session.new got no reply in time */
 export declare class BrowserStartTimeoutError extends Error {
     constructor(label: string, timeout: number);
@@ -39,7 +31,7 @@ export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPa
 export interface BrowserLaunchOptions {
     /** Which port to use for the WebDeveloper tools */
     port: number;
-    /** Firefox only */
+    /** The browser profile folder: user.js goes in it for Firefox, Chrome's user data for Chrome */
     profileDir: string;
     /** Start the browser in headless mode or in UI mode */
     headless: boolean;
@@ -60,10 +52,12 @@ export declare class Browser {
     /** Where downloads are saved; undefined when the browser could not be told (it then uses its own folder) */
     readonly downloadsDir: string | undefined;
     private exitedPromise;
-    constructor({ browserProc, biDiConnector, downloadsDir, }: {
-        browserProc: ChildProcessWithoutNullStreams;
+    private downloadFolders;
+    constructor({ browserProc, biDiConnector, downloadsDir, downloadFolders, }: {
+        browserProc: BrowserProcess;
         biDiConnector: BiDiConnector;
         downloadsDir?: string | undefined;
+        downloadFolders?: ChromeDownloadFolders | undefined;
     });
     /** Resolves when the browser process has exited, whether `close()` or a person closed it */
     get exited(): Promise<void>;
@@ -73,6 +67,8 @@ export declare class Browser {
         browser: Browser;
         page: Page;
     }>;
+    /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */
+    private static attach;
     /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
     close(): Promise<void>;
     /** Alias of close() */

package/dist/browser/browser.js

@@ -6,18 +6,15 @@ import path from "node:path";
 import { BiDiConnector, DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import Page from "./page.js";
+import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+import { launchChrome } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import { validateEmulation } from "./emulation.js";
 import { prepareDownloadsDir, removeIfEmpty } from "./downloads-dir.js";
+import { ChromeDownloadFolders } from "./download-folders.js";
 import logger from "../logger/index.js";
 import { browsersDir, projectDir, readConfig } from "../config/config.js";
-/**
- * Sent with session.new. With "ignore" the browser leaves a JavaScript dialog open and reports it
- * (`browsingContext.userPromptOpened`), so the framework decides how to answer instead of the browser.
- */
-export const SESSION_CAPABILITIES = {
-    alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } },
-};
+export { SESSION_CAPABILITIES };
 /** session.new waits at least this long (ms): the first start after an install can take a while (macOS checks the new app) */
 const SESSION_START_TIMEOUT = 120_000;
 /** session.new got no reply in time */
@@ -43,7 +40,8 @@ export async function startSession(connector, label, commandTimeout) {
 const BROWSER_CLOSE_GRACE = 2000;
 const browserProfilePath = (browserName) => path.join(browsersDir(), "profiles", browserName, "user.js");
 const baseBrowserLaunchFlags = {
-    // chrome: [],
+    // Chrome is started by its chromedriver: see chrome-launch.ts
+    chrome: [],
     firefox: ["--no-sandbox", "--no-remote"],
 };
 /** Read when a browser launches, since the profile folder depends on the active project */
@@ -52,10 +50,6 @@ const defaultLaunchOptions = (browserName) => ({
     profileDir: path.dirname(browserProfilePath(browserName)),
     headless: true,
 });
-const regexPrefix = {
-    firefox: /WebDriver\sBiDi\slistening\son\s/,
-    // chrome: /DevTools\slistening\son/,
-};
 export const browserLaunchFlag = (browserName, launchOptions) => {
     const defLaunchOpts = defaultLaunchOptions(browserName);
     const port = launchOptions.port || defLaunchOpts.port;
@@ -67,9 +61,8 @@ export const browserLaunchFlag = (browserName, launchOptions) => {
     }
     baseLaunchFlags.push(`--remote-debugging-port=${port}`);
     switch (browserName) {
-        // case "chrome":
-        //   baseLaunchFlags.push(`--user-data-dir=${profileDir}`);
-        // break;
+        case "chrome":
+            break;
         case "firefox":
             baseLaunchFlags.push("--profile", profileDir);
             // The home page (about:home) is privileged: BiDi refuses commands such as setViewport on it
@@ -97,6 +90,8 @@ export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(b
     mkdirSync(appDataPath, { recursive: true });
     logger.debug("Using app data dir for %s: %s", browserName, appDataPath);
     switch (browserName) {
+        case "chrome":
+            return {};
         case "firefox":
             // The project profile may have been opened by a newer Firefox (the system one, before 0.6);
             // without this Firefox refuses to start on it
@@ -104,7 +99,8 @@ export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(b
     }
 };
 const browserProfiles = {
-    // chrome: "",
+    // Chrome needs no prefs file; its profile folder is created at launch
+    chrome: "",
     firefox: `
     user_pref("devtools.debugger.remote-enabled", true);
     user_pref("devtools.debugger.prompt-connection", false);
@@ -116,17 +112,12 @@ const browserProfiles = {
   `,
 };
 // Firefox logs "WebDriver BiDi listening on ws://<host>:<port>" without the endpoint path
-const browserWsPath = {
-    firefox: "/session",
-};
-const browserWsRegex = {
-    firefox: /ws:\/\/(\d){1,3}.(\d){1,3}.(\d){1,3}.(\d){1,3}:(\d){4}/g,
-    // chrome:
-    //   /ws:\/\/(\d){1,3}.(\d){1,3}.(\d){1,3}.(\d){1,3}:(\d){4}\/devtools\/browser\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g,
-};
+const FIREFOX_WS_PATH = "/session";
+const FIREFOX_WS_REGEX = /ws:\/\/(\d){1,3}.(\d){1,3}.(\d){1,3}.(\d){1,3}:(\d){4}/g;
 export class Browser {
-    constructor({ browserProc, biDiConnector, downloadsDir, }) {
+    constructor({ browserProc, biDiConnector, downloadsDir, downloadFolders, }) {
         this.userContexts = new Map();
+        this.downloadFolders = downloadFolders;
         this.browserProc = browserProc;
         this.biDiConnector = biDiConnector;
         this.downloadsDir = downloadsDir;
@@ -151,9 +142,29 @@ export class Browser {
     signal) {
         signal?.throwIfAborted();
         logger.verbose("Trying to launch browser %s", browserName);
-        const { executablePath: browserLocation, label } = await projectBrowser(browserName);
+        const resolved = await projectBrowser(browserName);
+        const { executablePath: browserLocation, label } = resolved;
         logger.debug("Found browser install location at: %s", browserLocation);
         ensureBrowserProfile(browserName);
+        if (browserName === "chrome") {
+            const commandTimeout = await readCommandTimeout();
+            const { proc, connector } = await launchChrome({
+                executablePath: browserLocation,
+                driverPath: resolved.driverPath,
+                profileDir: launchOptions.profileDir ?? defaultLaunchOptions("chrome").profileDir,
+                headless: launchOptions.headless ?? defaultLaunchOptions("chrome").headless,
+                commandTimeout,
+                signal,
+            });
+            try {
+                // The chromedriver session is the BiDi session: there is no session.new to send
+                return await Browser.attach(proc, connector, browserName);
+            }
+            catch (err) {
+                abandonLaunch(proc, connector);
+                throw err;
+            }
+        }
         logger.verbose("Trying to spawn %s process", browserName);
         const browserProc = spawn(browserLocation, browserLaunchFlag(browserName, launchOptions), { env: { ...process.env, ...browserLaunchEnv(browserName) } });
         return new Promise((resolve, reject) => {
@@ -176,7 +187,7 @@ export class Browser {
             });
             browserProc.stderr.on("data", async (data) => {
                 logger.debug(`${browserName} stderr: ${data}`);
-                const urlMatch = String(data).match(browserWsRegex[browserName]);
+                const urlMatch = String(data).match(FIREFOX_WS_REGEX);
                 logger.debug("Browser announced its endpoint", { urlMatch });
                 if (!Array.isArray(urlMatch) || urlMatch.length === 0) {
                     return;
@@ -185,7 +196,7 @@ export class Browser {
                 // instead of an unhandled rejection from this async listener
                 let biDiConnector;
                 try {
-                    let url = urlMatch[0] + browserWsPath[browserName];
+                    let url = urlMatch[0] + FIREFOX_WS_PATH;
                     logger.verbose("Websocket URL match: %s", url);
                     const commandTimeout = await readCommandTimeout();
                     biDiConnector = await BiDiConnector.connect(url, { commandTimeout });
@@ -194,38 +205,10 @@ export class Browser {
                     logger.verbose("Session status", status);
                     await startSession(biDiConnector, label, commandTimeout);
                     logger.verbose("Session started successfully");
-                    const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readOptionalConfig("downloadsDir")) ?? "result/downloads"));
-                    const browser = new Browser({
-                        browserProc,
-                        biDiConnector,
-                        downloadsDir,
-                    });
-                    logger.verbose("Requesting current browser tree");
-                    const browserTree = await biDiConnector.send("browsingContext.getTree", {});
-                    logger.verbose("Received current browser tree");
-                    logger.debug("Browser tree: ", { browserTree });
-                    const pageContext = browserTree.contexts[0];
-                    let page = undefined;
-                    if (pageContext) {
-                        page = new Page(biDiConnector, pageContext.context);
-                        browser.defaultContext.register(page);
-                    }
-                    else {
-                        page = await browser.newPage({ type: "tab" });
-                    }
-                    await page.applyDefaultViewport();
-                    // Requests made before tracking starts are invisible to it, and a dialog nobody watches would hang the page
-                    await page.startNetworkTracking();
-                    await page.startDialogHandling();
-                    await page.startLogging();
-                    await page.startDownloadTracking();
-                    await page.startFileChooserTracking();
+                    const launched = await Browser.attach(browserProc, biDiConnector, browserName);
                     browserProc.off("close", onUnexpectedClose);
                     signal?.removeEventListener("abort", onAbort);
-                    resolve({
-                        browser,
-                        page,
-                    });
+                    resolve(launched);
                 }
                 catch (err) {
                     browserProc.off("close", onUnexpectedClose);
@@ -236,8 +219,46 @@ export class Browser {
             });
         });
     }
+    /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */
+    static async attach(browserProc, biDiConnector, browserName) {
+        biDiConnector.browserName = browserName;
+        const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readOptionalConfig("downloadsDir")) ?? "result/downloads"));
+        // Chrome replaces a file that has the name of a download; this keeps every download
+        const downloadFolders = browserName === "chrome" && downloadsDir
+            ? new ChromeDownloadFolders(biDiConnector, downloadsDir)
+            : undefined;
+        await downloadFolders?.start();
+        const browser = new Browser({
+            browserProc,
+            biDiConnector,
+            downloadsDir,
+            downloadFolders,
+        });
+        logger.verbose("Requesting current browser tree");
+        const browserTree = await biDiConnector.send("browsingContext.getTree", {});
+        logger.verbose("Received current browser tree");
+        logger.debug("Browser tree: ", { browserTree });
+        const pageContext = browserTree.contexts[0];
+        let page = undefined;
+        if (pageContext) {
+            page = new Page(biDiConnector, pageContext.context);
+            browser.defaultContext.register(page);
+        }
+        else {
+            page = await browser.newPage({ type: "tab" });
+        }
+        await page.applyDefaultViewport();
+        // Requests made before tracking starts are invisible to it, and a dialog nobody watches would hang the page
+        await page.startNetworkTracking();
+        await page.startDialogHandling();
+        await page.startLogging();
+        await page.startDownloadTracking();
+        await page.startFileChooserTracking();
+        return { browser, page };
+    }
     /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
     async close() {
+        await this.downloadFolders?.dispose();
         if (this.browserProc.exitCode !== null || this.browserProc.signalCode) {
             this.biDiConnector.kill();
             removeIfEmpty(this.downloadsDir);

package/dist/browser/chrome-launch.d.ts

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import EventEmitter from "node:events";
+import { BiDiConnector } from "../transport/bidi-connection.js";
+/** What `Browser` needs of the thing it launched: the browser process, or for Chrome the chromedriver in front of it */
+export interface BrowserProcess {
+    readonly exitCode: number | null;
+    readonly signalCode: NodeJS.Signals | null;
+    once(event: "exit", listener: (...args: any[]) => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
+}
+export interface ChromeLaunch {
+    executablePath: string;
+    driverPath: string;
+    profileDir: string;
+    headless: boolean;
+    commandTimeout: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export declare const chromeFlags: ({ headless, profileDir, }: Pick<ChromeLaunch, "headless" | "profileDir">) => string[];
+/** The capabilities chromedriver gets: a classic session that also opens a BiDi socket */
+export declare const chromeCapabilities: (launch: ChromeLaunch) => {
+    capabilities: {
+        alwaysMatch: {
+            "goog:chromeOptions": {
+                binary: string;
+                args: string[];
+            };
+            unhandledPromptBehavior: {
+                default: string;
+            };
+            browserName: string;
+            webSocketUrl: boolean;
+        };
+    };
+};
+/**
+ * Chrome speaks BiDi through its chromedriver: this starts one, asks it for a session with `webSocketUrl`, and
+ * connects to the socket it hands back. The session exists when this resolves, so there is no `session.new`.
+ * The returned process handle ends when the chromedriver does or the socket drops (a person closed the window).
+ */
+export declare function launchChrome(launch: ChromeLaunch): Promise<{
+    proc: BrowserProcess;
+    connector: BiDiConnector;
+}>;
+/** chromedriver as the process of a Chrome launch: ending it ends Chrome, and so does deleting the session */
+export declare class ChromeProcess extends EventEmitter implements BrowserProcess {
+    private driver;
+    private deleteSession;
+    session: string | undefined;
+    private done;
+    constructor(driver: Pick<ReturnType<typeof spawn>, "once" | "kill" | "exitCode" | "signalCode">, deleteSession?: (url: string) => Promise<unknown>);
+    get exitCode(): number | null;
+    get signalCode(): NodeJS.Signals | null;
+    /** The socket or the chromedriver is gone: the launch is over */
+    ended(): void;
+    kill(signal?: NodeJS.Signals): boolean;
+}

package/dist/browser/chrome-launch.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import EventEmitter from "node:events";
+import { mkdirSync } from "node:fs";
+import logger from "../logger/index.js";
+import { BiDiConnector } from "../transport/bidi-connection.js";
+import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+export const chromeFlags = ({ headless, profileDir, }) => [
+    "--no-sandbox",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-search-engine-choice-screen",
+    `--user-data-dir=${profileDir}`,
+    // Headless Chrome draws 15 px classic scrollbars inside the viewport; Firefox headless overlays them
+    ...(headless ? ["--headless=new", "--hide-scrollbars"] : []),
+];
+/** The capabilities chromedriver gets: a classic session that also opens a BiDi socket */
+export const chromeCapabilities = (launch) => ({
+    capabilities: {
+        alwaysMatch: {
+            browserName: "chrome",
+            webSocketUrl: true,
+            ...SESSION_CAPABILITIES.alwaysMatch,
+            "goog:chromeOptions": {
+                binary: launch.executablePath,
+                args: chromeFlags(launch),
+            },
+        },
+    },
+});
+/**
+ * Chrome speaks BiDi through its chromedriver: this starts one, asks it for a session with `webSocketUrl`, and
+ * connects to the socket it hands back. The session exists when this resolves, so there is no `session.new`.
+ * The returned process handle ends when the chromedriver does or the socket drops (a person closed the window).
+ */
+export async function launchChrome(launch) {
+    mkdirSync(launch.profileDir, { recursive: true });
+    launch.signal?.throwIfAborted();
+    const driver = spawn(launch.driverPath, ["--port=0"], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const proc = new ChromeProcess(driver);
+    const onAbort = () => proc.kill();
+    launch.signal?.addEventListener("abort", onAbort, { once: true });
+    let connector;
+    try {
+        const port = await driverPort(driver);
+        const base = `http://127.0.0.1:${port}`;
+        const res = await fetch(`${base}/session`, {
+            method: "POST",
+            body: JSON.stringify(chromeCapabilities(launch)),
+            signal: launch.signal ?? null,
+        });
+        const body = (await res.json());
+        const { sessionId, capabilities } = body.value;
+        if (!res.ok || !sessionId || !capabilities?.webSocketUrl)
+            throw new Error(`chromedriver could not start Chrome: ${body.value.message ?? res.statusText}`);
+        proc.session = `${base}/session/${sessionId}`;
+        logger.verbose("Chrome BiDi socket: %s", capabilities.webSocketUrl);
+        connector = await BiDiConnector.connect(capabilities.webSocketUrl, {
+            ...(launch.commandTimeout !== undefined && {
+                commandTimeout: launch.commandTimeout,
+            }),
+        });
+        connector.onClosed(() => proc.ended());
+        return { proc, connector };
+    }
+    catch (err) {
+        connector?.kill();
+        proc.kill();
+        if (launch.signal?.aborted)
+            throw launch.signal.reason;
+        throw err;
+    }
+    finally {
+        launch.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function driverPort(driver) {
+    return new Promise((resolve, reject) => {
+        const onData = (data) => {
+            logger.debug(`chromedriver: ${data}`);
+            const match = String(data).match(/started successfully on port (\d+)/);
+            if (match)
+                resolve(Number(match[1]));
+        };
+        driver.stdout?.on("data", onData);
+        driver.stderr?.on("data", onData);
+        driver.once("error", reject);
+        driver.once("exit", (code) => reject(new Error(`chromedriver exited with code ${code} before it was ready`)));
+    });
+}
+/** chromedriver as the process of a Chrome launch: ending it ends Chrome, and so does deleting the session */
+export class ChromeProcess extends EventEmitter {
+    constructor(driver, deleteSession = (url) => fetch(url, { method: "DELETE" })) {
+        super();
+        this.driver = driver;
+        this.deleteSession = deleteSession;
+        this.done = false;
+        driver.once("exit", () => this.ended());
+    }
+    get exitCode() {
+        return this.done ? (this.driver.exitCode ?? 0) : null;
+    }
+    get signalCode() {
+        return this.driver.signalCode;
+    }
+    /** The socket or the chromedriver is gone: the launch is over */
+    ended() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.emit("exit");
+        this.driver.kill();
+    }
+    kill(signal) {
+        // Deleting the session makes chromedriver quit Chrome; killing chromedriver alone could leave it running
+        const session = this.session;
+        this.session = undefined;
+        if (session) {
+            this.deleteSession(session)
+                .catch(() => undefined)
+                .finally(() => this.driver.kill(signal));
+            return true;
+        }
+        return this.driver.kill(signal);
+    }
+}

package/dist/browser/download-folders.d.ts

@@ -0,0 +1,27 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** `report.csv` becomes `report(1).csv`, `report(2).csv`, … (the names Firefox gives) until a name is free in `dir` */
+export declare function uniqueName(dir: string, name: string): string;
+/**
+ * Chrome saves a download under its suggested name and replaces a file that has it already, where Firefox picks a
+ * free name. This gives every download a folder of its own while it is written (the next folder is set when a download
+ * begins) and moves the finished file into the downloads folder under a free name, so no download replaces another.
+ * Must be started before the download trackers: it rewrites `filepath` of `downloadEnd` for them.
+ */
+export declare class ChromeDownloadFolders {
+    private connector;
+    private dir;
+    private subscription;
+    private staging;
+    private counter;
+    private disposed;
+    constructor(connector: BiDiConnector, dir: string);
+    start(): Promise<void>;
+    /** Idempotent */
+    dispose(): Promise<void>;
+    private stagingRoot;
+    /** Points the browser at a new, empty folder for the download after this one */
+    private rotate;
+    private removeIfEmpty;
+    private onBegin;
+    private onEnd;
+}