@itmetsam/samurai-framework 0.8.0 → 0.10.0

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;

package/dist/browser/page-logs.js

@@ -28,19 +28,37 @@ export class ConsoleMessage {
     /** Where the call was made, when the browser says */
     location() {
         const frame = this.stackTrace?.callFrames[0];
-        return frame && { url: frame.url, lineNumber: frame.lineNumber, columnNumber: frame.columnNumber };
+        return (frame && {
+            url: frame.url,
+            lineNumber: frame.lineNumber,
+            columnNumber: frame.columnNumber,
+        });
     }
 }
+/**
+ * Chrome starts the text of an unhandled promise rejection with this; Firefox does not. Removed, so a page error
+ * reads the same on both browsers.
+ */
+const REJECTION_PREFIX = "Uncaught (in promise) ";
+/** The text of a page error as it reads on every browser */
+export function pageErrorText(text) {
+    return text.startsWith(REJECTION_PREFIX)
+        ? text.slice(REJECTION_PREFIX.length)
+        : text;
+}
 /** An exception nobody caught in the page */
 export class PageError extends Error {
     constructor(text, timestamp, stackTrace) {
         super(text);
         this.name = "PageError";
         this.timestamp = timestamp;
-        this.stack = [text, ...(stackTrace?.callFrames ?? []).map(formatFrame)].join("\n");
+        this.stack = [
+            text,
+            ...(stackTrace?.callFrames ?? []).map(formatFrame),
+        ].join("\n");
     }
 }
-function formatFrame({ functionName, url, lineNumber, columnNumber }) {
+function formatFrame({ functionName, url, lineNumber, columnNumber, }) {
     const where = `${url}:${lineNumber}:${columnNumber}`;
     return functionName ? `    at ${functionName} (${where})` : `    at ${where}`;
 }
@@ -68,7 +86,9 @@ export class PageLogs {
             const record = {
                 level: entry.level,
                 type: entry.type,
-                ...(entry.type === "console" && { method: entry.method }),
+                ...(entry.type === "console" && {
+                    method: entry.method,
+                }),
                 text,
                 timestamp: entry.timestamp,
             };
@@ -82,7 +102,7 @@ export class PageLogs {
                 this.emit("console", new ConsoleMessage(entry.level, consoleEntry.method, text, (consoleEntry.args ?? []).map((arg) => fromRemoteValue(arg)), entry.timestamp, entry.stackTrace));
             }
             else if (entry.type === "javascript") {
-                const error = new PageError(text, entry.timestamp, entry.stackTrace);
+                const error = new PageError(pageErrorText(text), entry.timestamp, entry.stackTrace);
                 this.uncaught.push(error);
                 if (this.uncaught.length > this.maxEntries)
                     this.uncaught.shift();

package/dist/browser/page.d.ts

@@ -171,6 +171,17 @@ export default class Page {
     /** Goes forward one entry in the history. False when there is none */
     goForward(): Promise<boolean>;
     private traverse;
+    /**
+     * Whether going back would only reach the blank page a tab starts with. Firefox does not keep that page in the
+     * history, Chrome does; the Navigation API (Chrome only) lets Chrome say the same as Firefox.
+     */
+    private atFirstEntry;
+    /**
+     * Starts listening for the end of a history traversal (the new entry committed, or the history or fragment changed
+     * within the document). `done` resolves at the first such event, or after a second without one (a page restored from
+     * the back-forward cache may say nothing); it never rejects.
+     */
+    private watchHistoryTraversal;
     /** The URL of the page now */
     url(): Promise<string>;
     /** The title of the document now */
@@ -185,6 +196,13 @@ export default class Page {
         height: number;
         devicePixelRatio?: number;
     } | null): Promise<void>;
+    /**
+     * Runs `change`, then waits until the page has stopped resizing. Chrome answers a viewport reset before the window
+     * has its own size back, so a read right after it can still show the old size. The wait ends 50 ms after the last
+     * `resize` event, and after 300 ms when the size does not change at all (no event comes). Never fails: a page that
+     * cannot be watched is simply not waited for.
+     */
+    private untilResized;
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     applyDefaultViewport(): Promise<void>;
     /**

package/dist/browser/page.js

@@ -31,6 +31,8 @@ import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
 import { callFunction } from "../script/call-function.js";
 /** Time (ms) a navigation or a wait for a load state may take */
 const DEFAULT_NAVIGATION_TIMEOUT = 30000;
+/** Time (ms) a history traversal may go without a sign that the entry is shown before it is taken as done */
+const HISTORY_SETTLE_TIMEOUT = 1000;
 /** Time (ms) without requests in flight that counts as idle */
 const DEFAULT_IDLE_TIME = 500;
 /** The size a page gets unless config `use.viewport` says otherwise */
@@ -336,11 +338,17 @@ export default class Page {
     }
     async traverse(delta) {
         this.assertOpen();
+        if (delta === -1 && (await this.atFirstEntry()))
+            return false;
+        const settled = await this.watchHistoryTraversal();
         try {
             await this.biDiConnector.send("browsingContext.traverseHistory", {
                 context: this.id,
                 delta,
             });
+            // Firefox answers once the entry is shown; Chrome answers before, and a script call in between can hit the
+            // document that is going away
+            await settled.done;
             return true;
         }
         catch (err) {
@@ -348,6 +356,66 @@ export default class Page {
                 return false;
             throw err;
         }
+        finally {
+            await settled.stop();
+        }
+    }
+    /**
+     * Whether going back would only reach the blank page a tab starts with. Firefox does not keep that page in the
+     * history, Chrome does; the Navigation API (Chrome only) lets Chrome say the same as Firefox.
+     */
+    async atFirstEntry() {
+        try {
+            return await callFunction(this.biDiConnector, this.id, `() => {
+          const nav = globalThis.navigation;
+          if (!nav) return false;
+          const entries = nav.entries();
+          const index = nav.currentEntry.index;
+          return index === 0 || (index === 1 && entries[0].url === "about:blank");
+        }`, [], { awaitPromise: false });
+        }
+        catch (err) {
+            logger.debug("Could not read the history position", { err });
+            return false;
+        }
+    }
+    /**
+     * Starts listening for the end of a history traversal (the new entry committed, or the history or fragment changed
+     * within the document). `done` resolves at the first such event, or after a second without one (a page restored from
+     * the back-forward cache may say nothing); it never rejects.
+     */
+    async watchHistoryTraversal() {
+        const events = [
+            "browsingContext.navigationCommitted",
+            "browsingContext.historyUpdated",
+            "browsingContext.fragmentNavigated",
+        ];
+        let subscription;
+        try {
+            subscription = await this.biDiConnector.subscribe([...events]);
+        }
+        catch (err) {
+            logger.debug("Could not watch a history traversal", { err });
+            return { done: Promise.resolve(), stop: async () => { } };
+        }
+        let finish;
+        const done = new Promise((resolve) => (finish = resolve));
+        const timer = setTimeout(finish, HISTORY_SETTLE_TIMEOUT);
+        const listener = (info) => {
+            if (info.context === this.id)
+                finish();
+        };
+        for (const event of events)
+            this.biDiConnector.onEvent(event, listener);
+        return {
+            done,
+            stop: async () => {
+                clearTimeout(timer);
+                for (const event of events)
+                    this.biDiConnector.offEvent(event, listener);
+                await subscription?.unsubscribe().catch(() => undefined);
+            },
+        };
     }
     /** The URL of the page now */
     async url() {
@@ -367,11 +435,11 @@ export default class Page {
     async setViewport(viewport) {
         this.assertOpen();
         if (viewport === null) {
-            await this.biDiConnector.send("browsingContext.setViewport", {
+            await this.untilResized(() => this.biDiConnector.send("browsingContext.setViewport", {
                 context: this.id,
                 viewport: null,
                 devicePixelRatio: null,
-            });
+            }));
             return;
         }
         const { width, height, devicePixelRatio } = viewport;
@@ -393,6 +461,35 @@ export default class Page {
             ...(devicePixelRatio !== undefined && { devicePixelRatio }),
         });
     }
+    /**
+     * Runs `change`, then waits until the page has stopped resizing. Chrome answers a viewport reset before the window
+     * has its own size back, so a read right after it can still show the old size. The wait ends 50 ms after the last
+     * `resize` event, and after 300 ms when the size does not change at all (no event comes). Never fails: a page that
+     * cannot be watched is simply not waited for.
+     */
+    async untilResized(change) {
+        const sandbox = { sandbox: "samurai-viewport" };
+        const watching = await callFunction(this.biDiConnector, this.id, `() => {
+        globalThis.__resized = new Promise((resolve) => {
+          let timer;
+          const finish = () => {
+            clearTimeout(timer);
+            removeEventListener("resize", onResize);
+            resolve();
+          };
+          const onResize = () => {
+            clearTimeout(timer);
+            timer = setTimeout(finish, 50);
+          };
+          addEventListener("resize", onResize);
+          timer = setTimeout(finish, 300);
+        });
+      }`, [], { ...sandbox, awaitPromise: false }).then(() => true, () => false);
+        await change();
+        if (!watching)
+            return;
+        await callFunction(this.biDiConnector, this.id, "() => globalThis.__resized", [], sandbox).catch(() => undefined);
+    }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {
         const { viewport } = this.settings?.use ?? (await readSection("use"));

package/dist/browser/screenshot.js

@@ -1,5 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { callFunction } from "../script/call-function.js";
+import { ElementHandle } from "../script/element-handle.js";
 const MIME = { png: "image/png", jpeg: "image/jpeg" };
 /** The `format` of a capture command; validates the type/quality combination */
 function imageFormat({ type, quality, }) {
@@ -23,12 +25,17 @@ function imageFormat({ type, quality, }) {
  */
 export async function takeScreenshot(connector, context, options = {}, element) {
     const format = imageFormat(options);
+    // An element is captured as its box in the document: Chrome cannot capture an `element` clip that is not
+    // wholly in the viewport, and this works the same for an element taller than the viewport
     const clip = element
-        ? { type: "element", element: { sharedId: element.sharedId } }
+        ? {
+            type: "box",
+            ...(await documentBox(connector, context, element)),
+        }
         : options.clip && { type: "box", ...options.clip };
     const { data } = await connector.send("browsingContext.captureScreenshot", {
         context,
-        ...(options.fullPage && { origin: "document" }),
+        ...((options.fullPage || element) && { origin: "document" }),
         ...(format && { format }),
         ...(clip && { clip }),
     });
@@ -36,6 +43,13 @@ export async function takeScreenshot(connector, context, options = {}, element)
     await writeOutput(options.path, image);
     return image;
 }
+/** The element's box in document coordinates (CSS pixels) */
+async function documentBox(connector, context, element) {
+    return callFunction(connector, context, `(el) => {
+      const r = el.getBoundingClientRect();
+      return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height };
+    }`, [new ElementHandle(element.sharedId)]);
+}
 /** Writes `data` to `file`, creating the folders; nothing happens without a path */
 export async function writeOutput(file, data) {
     if (!file)

package/dist/browser/session-capabilities.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sent with session.new (Firefox) or as capabilities of the chromedriver session (Chrome). 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;
+        };
+    };
+};

package/dist/browser/session-capabilities.js

@@ -0,0 +1,8 @@
+/**
+ * Sent with session.new (Firefox) or as capabilities of the chromedriver session (Chrome). 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" } },
+};

package/dist/browsers/index.d.ts

@@ -1,6 +1,6 @@
 export { browsersCacheDir } from "./cache-dir.js";
 export type { CachedBuild, Downloader } from "./downloader.js";
-export { ENV_PATH, type Override } from "./overrides.js";
+export { ENV_CHROMEDRIVER_PATH, ENV_PATH, type Override } from "./overrides.js";
 export { LAUNCHABLE, MANAGED_BROWSERS, PINNED, isManagedBrowser, type ManagedBrowser, } from "./pins.js";
 export { browserStatus, projectBrowser, projectExecutable, resolveBrowser, resolveExecutable, type ResolvedBrowser, } from "./resolve.js";
-export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedExecutable, uninstallBrowser, type BrowserStatus, type InstalledBuild, type StoreOptions, } from "./store.js";
+export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedChromedriver, managedExecutable, uninstallBrowser, type BrowserStatus, type InstalledBuild, type StoreOptions, } from "./store.js";

package/dist/browsers/index.js

@@ -1,5 +1,5 @@
 export { browsersCacheDir } from "./cache-dir.js";
-export { ENV_PATH } from "./overrides.js";
+export { ENV_CHROMEDRIVER_PATH, ENV_PATH } from "./overrides.js";
 export { LAUNCHABLE, MANAGED_BROWSERS, PINNED, isManagedBrowser, } from "./pins.js";
 export { browserStatus, projectBrowser, projectExecutable, resolveBrowser, resolveExecutable, } from "./resolve.js";
-export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedExecutable, uninstallBrowser, } from "./store.js";
+export { BrowserNotInstalledError, installBrowser, listInstalled, managedBuildDir, managedChromedriver, managedExecutable, uninstallBrowser, } from "./store.js";

package/dist/browsers/overrides.d.ts

@@ -12,6 +12,8 @@ export interface OverrideSources {
     /** What relative `browserPaths` resolve from */
     projectDir?: string;
 }
+/** Chrome is driven through a chromedriver of the same major version; this points a launch at another one */
+export declare const ENV_CHROMEDRIVER_PATH = "SAMURAI_CHROMEDRIVER_PATH";
 export declare const ENV_PATH: Record<ManagedBrowser, string>;
 /** The env variable, else the config's `browserPaths`; undefined: use the managed build */
 export declare function overrideOf(name: ManagedBrowser, { env, browserPaths, projectDir, }?: OverrideSources): Override | undefined;

package/dist/browsers/overrides.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+/** Chrome is driven through a chromedriver of the same major version; this points a launch at another one */
+export const ENV_CHROMEDRIVER_PATH = "SAMURAI_CHROMEDRIVER_PATH";
 export const ENV_PATH = {
     firefox: "SAMURAI_FIREFOX_PATH",
     chrome: "SAMURAI_CHROME_PATH",

package/dist/browsers/pins.d.ts

@@ -11,6 +11,6 @@ export declare const PINNED: {
 };
 export type ManagedBrowser = keyof typeof PINNED;
 export declare const MANAGED_BROWSERS: ManagedBrowser[];
-/** The managed browsers the framework can launch; Chrome joins when it can drive it */
+/** The managed browsers the framework can launch (Chrome through its chromedriver) */
 export declare const LAUNCHABLE: readonly ManagedBrowser[];
 export declare function isManagedBrowser(name: string): name is ManagedBrowser;

package/dist/browsers/pins.js

@@ -7,8 +7,8 @@ export const PINNED = {
     },
 };
 export const MANAGED_BROWSERS = Object.keys(PINNED);
-/** The managed browsers the framework can launch; Chrome joins when it can drive it */
-export const LAUNCHABLE = ["firefox"];
+/** The managed browsers the framework can launch (Chrome through its chromedriver) */
+export const LAUNCHABLE = ["firefox", "chrome"];
 export function isManagedBrowser(name) {
     return Object.prototype.hasOwnProperty.call(PINNED, name);
 }

package/dist/browsers/resolve.d.ts

@@ -9,6 +9,8 @@ export interface ResolvedBrowser {
     label: string;
     /** The managed build's folder; undefined when an env or config path is used instead */
     buildDir?: string;
+    /** Chrome only: the chromedriver that starts it and speaks BiDi for it */
+    driverPath?: string;
 }
 /** The browser a launch uses: the env path, else the config's `browserPaths`, else the pinned build. Never downloads */
 export declare function resolveBrowser(name: ManagedBrowser, sources?: OverrideSources & StoreOptions): ResolvedBrowser;

package/dist/browsers/resolve.js

@@ -1,17 +1,19 @@
 import { existsSync } from "node:fs";
 import { projectConfig, projectDir, readConfig } from "../config/config.js";
 import logger from "../logger/index.js";
-import { ENV_PATH, overrideOf } from "./overrides.js";
+import { ENV_CHROMEDRIVER_PATH, ENV_PATH, overrideOf, } from "./overrides.js";
 import { MANAGED_BROWSERS, PINNED } from "./pins.js";
-import { managedBuildDir, managedExecutable, statusOf, } from "./store.js";
+import { managedBuildDir, managedChromedriver, managedExecutable, statusOf, } from "./store.js";
 /** The browser a launch uses: the env path, else the config's `browserPaths`, else the pinned build. Never downloads */
 export function resolveBrowser(name, sources = {}) {
+    const driverPath = name === "chrome" ? resolveChromedriver(sources) : undefined;
     const override = overrideOf(name, sources);
     if (!override)
         return {
             executablePath: managedExecutable(name, sources),
             label: PINNED[name].label,
             buildDir: managedBuildDir(name, sources),
+            ...(driverPath && { driverPath }),
         };
     if (!existsSync(override.path))
         throw new Error(override.from === "env"
@@ -20,8 +22,18 @@ export function resolveBrowser(name, sources = {}) {
     return {
         executablePath: override.path,
         label: name.charAt(0).toUpperCase() + name.slice(1),
+        ...(driverPath && { driverPath }),
     };
 }
+/** `SAMURAI_CHROMEDRIVER_PATH` (which must exist), else the chromedriver installed with the pinned Chrome */
+function resolveChromedriver(sources) {
+    const fromEnv = (sources.env ?? process.env)[ENV_CHROMEDRIVER_PATH];
+    if (!fromEnv)
+        return managedChromedriver(sources);
+    if (!existsSync(fromEnv))
+        throw new Error(`${ENV_CHROMEDRIVER_PATH} points to a missing file: ${fromEnv}`);
+    return fromEnv;
+}
 /** The binary a launch uses; see `resolveBrowser` */
 export function resolveExecutable(name, sources = {}) {
     return resolveBrowser(name, sources).executablePath;

package/dist/browsers/store.d.ts

@@ -44,6 +44,8 @@ export declare function installBrowser(name: ManagedBrowser, options?: StoreOpti
 export declare function statusOf(name: ManagedBrowser, options?: StoreOptions & OverrideSources): BrowserStatus;
 /** The pinned build's executable; throws BrowserNotInstalledError when it isn't complete */
 export declare function managedExecutable(name: ManagedBrowser, options?: StoreOptions): string;
+/** The chromedriver installed with the pinned Chrome; throws BrowserNotInstalledError when Chrome's install isn't complete */
+export declare function managedChromedriver(options?: StoreOptions): string;
 /** The folder the pinned build of `name` is, or would be, installed in */
 export declare function managedBuildDir(name: ManagedBrowser, options?: StoreOptions): string;
 /** Removes a build (default: the pinned one); Chrome takes its chromedriver along */

package/dist/browsers/store.js

@@ -127,6 +127,14 @@ export function managedExecutable(name, options = {}) {
         throw new BrowserNotInstalledError(name, status.label);
     return status.executablePath;
 }
+/** The chromedriver installed with the pinned Chrome; throws BrowserNotInstalledError when Chrome's install isn't complete */
+export function managedChromedriver(options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const status = statusOf("chrome", { ...options, env: {} });
+    if (status.state !== "installed")
+        throw new BrowserNotInstalledError("chrome", status.label);
+    return downloader.executablePath(cacheDir, "chromedriver", PINNED.chrome.buildId);
+}
 /** The folder the pinned build of `name` is, or would be, installed in */
 export function managedBuildDir(name, options = {}) {
     const { cacheDir, downloader } = store(options);

package/dist/cli/args.d.ts

@@ -1,4 +1,6 @@
-import type { ProjectOptions } from "../runner/run.js";
+import { type ProjectOptions, type RunnerOptions } from "../runner/run.js";
+/** `firefox` or `chrome` */
+type SupportedBrowser = NonNullable<RunnerOptions["browsers"]>[number];
 /** The values a command line can override for one run */
 type RunOverrides = Pick<ProjectOptions, "environment" | "timeout" | "expectTimeout">;
 /** Flags and positional arguments of a command line; an unknown flag is an error */
@@ -11,6 +13,7 @@ export declare function parseCommandLine(argv: string[]): {
         port?: string | undefined;
         grep?: string | undefined;
         group?: string | undefined;
+        browser?: string[] | undefined;
         file?: string[] | undefined;
         json?: boolean | undefined;
         all?: boolean | undefined;
@@ -33,8 +36,10 @@ export interface RunnerFlags {
     grep?: string;
     group?: string;
     files?: string[];
+    /** `--browser`, repeated for more than one; replaces the config's `browsers` for this run */
+    browsers?: SupportedBrowser[];
 }
-/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>` and `--file <spec>` (repeatable) from `argv` */
+/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv` */
 export declare function parseRunnerFlags(argv: string[]): RunnerFlags;
 /** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
 export declare function parseRunOverrides(argv: string[], env?: Partial<NodeJS.ProcessEnv>): RunOverrides;

package/dist/cli/args.js

@@ -1,4 +1,5 @@
 import { parseArgs } from "node:util";
+import { checkBrowserList, } from "../runner/run.js";
 const FLAGS = {
     env: { type: "string" },
     timeout: { type: "string" },
@@ -7,6 +8,7 @@ const FLAGS = {
     port: { type: "string" },
     grep: { type: "string" },
     group: { type: "string" },
+    browser: { type: "string", multiple: true },
     file: { type: "string", multiple: true },
     json: { type: "boolean" },
     all: { type: "boolean" },
@@ -33,7 +35,7 @@ export function parseCommandLine(argv) {
 function parseFlags(argv) {
     return parseCommandLine(argv).values;
 }
-/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>` and `--file <spec>` (repeatable) from `argv` */
+/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv` */
 export function parseRunnerFlags(argv) {
     const values = parseFlags(argv);
     const flags = {};
@@ -52,6 +54,10 @@ export function parseRunnerFlags(argv) {
         flags.group = values.group;
     if (values.file?.length)
         flags.files = values.file;
+    if (values.browser?.length) {
+        checkBrowserList(values.browser, "--browser");
+        flags.browsers = values.browser;
+    }
     return flags;
 }
 /** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */

package/dist/cli/console-reporter.d.ts

@@ -8,8 +8,12 @@ export interface ConsoleReporterOptions {
 export declare class ConsoleReporter {
     private readonly write;
     private readonly paint;
+    /** Whether the run has more than one browser: only then is each test labelled with its browser */
+    private labelled;
     constructor({ write, color }: ConsoleReporterOptions);
     handle(event: RunEvent): void;
+    /** ` [chrome]` in a run with more than one browser, else nothing */
+    private tag;
     private line;
     private summary;
 }