@itmetsam/samurai-framework 0.8.0 → 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)
 
@@ -146,10 +146,10 @@ The [documentation index](docs/README.md) lists every guide and design note by t
 
 ## Scripts
 
-| 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 (needs Firefox)  |
-| `bun run test:cli`     | Tests of the `samurai` command (build first)    |
-| `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/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;
+}

package/dist/browser/download-folders.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, } from "node:fs";
+import path from "node:path";
+import logger from "../logger/index.js";
+/** `report.csv` becomes `report(1).csv`, `report(2).csv`, … (the names Firefox gives) until a name is free in `dir` */
+export function uniqueName(dir, name) {
+    if (!existsSync(path.join(dir, name)))
+        return name;
+    const { name: stem, ext } = path.parse(name);
+    for (let n = 1;; n++) {
+        const candidate = `${stem}(${n})${ext}`;
+        if (!existsSync(path.join(dir, candidate)))
+            return candidate;
+    }
+}
+/**
+ * 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 class ChromeDownloadFolders {
+    constructor(connector, dir) {
+        this.connector = connector;
+        this.dir = dir;
+        this.counter = 0;
+        this.disposed = false;
+        this.onBegin = (_params) => {
+            if (this.disposed)
+                return;
+            this.rotate().catch((err) => logger.error("Could not set a new download folder", { err }));
+        };
+        this.onEnd = (params) => {
+            if (this.disposed || params.status !== "complete")
+                return;
+            try {
+                const from = params.filepath;
+                const to = path.join(this.dir, uniqueName(this.dir, path.basename(from)));
+                renameSync(from, to);
+                params.filepath = to;
+                this.removeIfEmpty(path.dirname(from));
+            }
+            catch (err) {
+                logger.error("Could not move a finished download", { err });
+            }
+        };
+    }
+    async start() {
+        this.connector.onEvent("browsingContext.downloadWillBegin", this.onBegin);
+        this.connector.onEvent("browsingContext.downloadEnd", this.onEnd);
+        try {
+            this.subscription = await this.connector.subscribe([
+                "browsingContext.downloadWillBegin",
+                "browsingContext.downloadEnd",
+            ]);
+            await this.rotate();
+        }
+        catch (err) {
+            await this.dispose();
+            throw err;
+        }
+    }
+    /** Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.connector.offEvent("browsingContext.downloadWillBegin", this.onBegin);
+        this.connector.offEvent("browsingContext.downloadEnd", this.onEnd);
+        await this.subscription?.unsubscribe().catch(() => undefined);
+        if (this.staging)
+            this.removeIfEmpty(this.staging);
+        this.removeIfEmpty(this.stagingRoot());
+    }
+    stagingRoot() {
+        return path.join(this.dir, ".staging");
+    }
+    /** Points the browser at a new, empty folder for the download after this one */
+    async rotate() {
+        const previous = this.staging;
+        this.staging = path.join(this.stagingRoot(), String(this.counter++));
+        mkdirSync(this.staging, { recursive: true });
+        await this.connector.send("browser.setDownloadBehavior", {
+            downloadBehavior: { type: "allowed", destinationFolder: this.staging },
+        });
+        if (previous)
+            this.removeIfEmpty(previous);
+    }
+    removeIfEmpty(dir) {
+        try {
+            if (readdirSync(dir).length === 0)
+                rmSync(dir, { recursive: true });
+        }
+        catch {
+            // gone already, or not empty: leave it
+        }
+    }
+}

package/dist/browser/page-logs.d.ts

@@ -39,6 +39,8 @@ export declare class ConsoleMessage {
     /** Where the call was made, when the browser says */
     location(): SourceLocation | undefined;
 }
+/** The text of a page error as it reads on every browser */
+export declare function pageErrorText(text: string): string;
 /** An exception nobody caught in the page */
 export declare class PageError extends Error {
     readonly timestamp: number;