@itmetsam/samurai-framework 0.5.0 → 0.6.0

package/README.md

@@ -22,14 +22,14 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
 - **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. The UI that ties them together is not built yet (see the [roadmap](docs/roadmap.md)).
 
-> **Status:** early. Firefox only, run from a checkout of this repository (not published to npm yet). See [what is still open](docs/roadmap.md).
+> **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
 
 ## Getting started
 
 ### 1. Requirements
 
 - [Node.js](https://nodejs.org) 26 or newer and [Bun](https://bun.sh) 1.3 or newer (CI uses these versions)
-- Firefox installed on the machine. It is found in the usual install locations on Linux, macOS and Windows.
+- 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.
 
 ### 2. Install
 

package/dist/api.d.ts

@@ -1,4 +1,5 @@
 export { test, describe } from "./runner/registry.js";
 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";

package/dist/api.js

@@ -1,3 +1,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";

package/dist/browser/browser-finder.d.ts

@@ -1,2 +1,3 @@
 import type { SupportedBrowser } from "../types/browser.js";
+/** @deprecated Launches use the builds SAMURAI downloads (`samurai browsers install`); removed in a later major */
 export declare function findBrowser(browserName: SupportedBrowser): string;

package/dist/browser/browser-finder.js

@@ -7,6 +7,7 @@ const macBrowserPaths = {
     // 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 */
 export function findBrowser(browserName) {
     logger.verbose("Checking install location for %s", browserName);
     if (!supportedBrowsers.includes(browserName)) {

package/dist/browser/browser.d.ts

@@ -18,6 +18,12 @@ export declare const SESSION_CAPABILITIES: {
         };
     };
 };
+/** session.new got no reply in time */
+export declare class BrowserStartTimeoutError extends Error {
+    constructor(label: string, timeout: number);
+}
+/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
+export declare function startSession(connector: Pick<BiDiConnector, "send">, label: string, commandTimeout: number | undefined): Promise<void>;
 export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOptions: Partial<BrowserLaunchOptions>) => string[];
 /**
  * Stops what a failed launch started. A browser left running holds the profile (the next launch
@@ -28,6 +34,8 @@ export declare function abandonLaunch(browserProc: {
 }, biDiConnector: {
     kill(): void;
 } | undefined): void;
+/** Env added to a browser's process */
+export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPath?: string) => Record<string, string>;
 export interface BrowserLaunchOptions {
     /** Which port to use for the WebDeveloper tools */
     port: number;

package/dist/browser/browser.js

@@ -1,9 +1,10 @@
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { findBrowser } from "./browser-finder.js";
+import { projectBrowser } from "../browsers/resolve.js";
 import path from "node:path";
-import { BiDiConnector } from "../transport/bidi-connection.js";
+import { BiDiConnector, DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
+import { BiDiError } from "../transport/bidi-error.js";
 import Page from "./page.js";
 import { BrowserContext } from "./browser-context.js";
 import { validateEmulation } from "./emulation.js";
@@ -17,6 +18,27 @@ import { browsersDir, projectDir, readConfig } from "../config/config.js";
 export const SESSION_CAPABILITIES = {
     alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } },
 };
+/** 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 */
+export class BrowserStartTimeoutError extends Error {
+    constructor(label, timeout) {
+        super(`${label} did not finish starting within ${Math.round(timeout / 1000)}s. The first start after an install can be slow; run again.`);
+        this.name = "BrowserStartTimeoutError";
+    }
+}
+/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
+export async function startSession(connector, label, commandTimeout) {
+    const timeout = Math.max(commandTimeout ?? DEFAULT_COMMAND_TIMEOUT, SESSION_START_TIMEOUT);
+    try {
+        await connector.send("session.new", { capabilities: SESSION_CAPABILITIES }, { timeout });
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "timeout")
+            throw new BrowserStartTimeoutError(label, timeout);
+        throw err;
+    }
+}
 /** Time (ms) to wait for Firefox to answer browser.close before killing the process */
 const BROWSER_CLOSE_GRACE = 2000;
 const browserProfilePath = (browserName) => path.join(browsersDir(), "profiles", browserName, "user.js");
@@ -70,13 +92,15 @@ export function abandonLaunch(browserProc, biDiConnector) {
 // On macOS a spawned browser is attributed to the terminal, which is denied access to
 // ~/Library/Application Support/Firefox (profiles.ini). Point Firefox at a local app data dir instead.
 const browserAppDataPath = (browserName) => path.join(browsersDir(), "app-data", browserName);
-const browserLaunchEnv = (browserName) => {
-    const appDataPath = browserAppDataPath(browserName);
+/** Env added to a browser's process */
+export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(browserName)) => {
     mkdirSync(appDataPath, { recursive: true });
     logger.debug("Using app data dir for %s: %s", browserName, appDataPath);
     switch (browserName) {
         case "firefox":
-            return { MOZ_APP_DATA: appDataPath };
+            // 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
+            return { MOZ_APP_DATA: appDataPath, MOZ_ALLOW_DOWNGRADE: "1" };
     }
 };
 const browserProfiles = {
@@ -127,7 +151,7 @@ export class Browser {
     signal) {
         signal?.throwIfAborted();
         logger.verbose("Trying to launch browser %s", browserName);
-        const browserLocation = findBrowser(browserName);
+        const { executablePath: browserLocation, label } = await projectBrowser(browserName);
         logger.debug("Found browser install location at: %s", browserLocation);
         ensureBrowserProfile(browserName);
         logger.verbose("Trying to spawn %s process", browserName);
@@ -163,15 +187,12 @@ export class Browser {
                 try {
                     let url = urlMatch[0] + browserWsPath[browserName];
                     logger.verbose("Websocket URL match: %s", url);
-                    biDiConnector = await BiDiConnector.connect(url, {
-                        commandTimeout: await readCommandTimeout(),
-                    });
+                    const commandTimeout = await readCommandTimeout();
+                    biDiConnector = await BiDiConnector.connect(url, { commandTimeout });
                     logger.verbose("Starting new session");
                     const status = await biDiConnector.send("session.status", {});
                     logger.verbose("Session status", status);
-                    await biDiConnector.send("session.new", {
-                        capabilities: SESSION_CAPABILITIES,
-                    });
+                    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({

package/dist/browser/warm-up.d.ts

@@ -0,0 +1,14 @@
+import { type ResolvedBrowser } from "../browsers/resolve.js";
+import type { SupportedBrowser } from "../types/browser.js";
+import { type BrowserLaunchOptions } from "./browser.js";
+/** Written into a managed build's folder once it started there; its first start can be slow (macOS checks the new app) */
+export declare const LAUNCHED_STAMP = ".samurai-launched";
+/**
+ * Starts a managed build once, before its first real use, so that slow first start happens outside a test's
+ * timeout. A browser set by env or config, a stamped build, and an aborted run are skipped.
+ */
+export declare function warmUp(target: ResolvedBrowser, launch: () => Promise<{
+    close(): Promise<void>;
+}>, signal?: AbortSignal): Promise<void>;
+/** Resolves the project's browser (throws when it is missing) and warms a managed build up, headless */
+export declare function ensureWarm(name: SupportedBrowser, launchOptions?: Partial<BrowserLaunchOptions>, signal?: AbortSignal): Promise<void>;

package/dist/browser/warm-up.js

@@ -0,0 +1,37 @@
+import { existsSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { projectBrowser } from "../browsers/resolve.js";
+import logger from "../logger/index.js";
+import { Browser, BrowserStartTimeoutError, } from "./browser.js";
+/** Written into a managed build's folder once it started there; its first start can be slow (macOS checks the new app) */
+export const LAUNCHED_STAMP = ".samurai-launched";
+/**
+ * Starts a managed build once, before its first real use, so that slow first start happens outside a test's
+ * timeout. A browser set by env or config, a stamped build, and an aborted run are skipped.
+ */
+export async function warmUp(target, launch, signal) {
+    if (!target.buildDir)
+        return;
+    const stamp = path.join(target.buildDir, LAUNCHED_STAMP);
+    if (existsSync(stamp) || signal?.aborted)
+        return;
+    logger.verbose("First start of %s", target.label);
+    let browser;
+    try {
+        browser = await launch();
+    }
+    catch (err) {
+        if (signal?.aborted)
+            return;
+        if (err instanceof BrowserStartTimeoutError)
+            throw err;
+        throw new Error(`Could not start ${target.label} for the first time: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    await browser.close();
+    writeFileSync(stamp, new Date().toISOString());
+}
+/** Resolves the project's browser (throws when it is missing) and warms a managed build up, headless */
+export async function ensureWarm(name, launchOptions = {}, signal) {
+    await warmUp(await projectBrowser(name), async () => (await Browser.launch(name, { ...launchOptions, headless: true }, signal))
+        .browser, signal);
+}

package/dist/browsers/cache-dir.d.ts

@@ -0,0 +1,2 @@
+/** Where downloaded browsers live, shared by every project of this user: `SAMURAI_BROWSERS_PATH`, else the OS cache folder */
+export declare function browsersCacheDir(env?: Partial<NodeJS.ProcessEnv>, platform?: NodeJS.Platform, home?: string): string;

package/dist/browsers/cache-dir.js

@@ -0,0 +1,15 @@
+import { homedir } from "node:os";
+import path from "node:path";
+/** Where downloaded browsers live, shared by every project of this user: `SAMURAI_BROWSERS_PATH`, else the OS cache folder */
+export function browsersCacheDir(env = process.env, platform = process.platform, home = homedir()) {
+    if (env.SAMURAI_BROWSERS_PATH)
+        return path.resolve(env.SAMURAI_BROWSERS_PATH);
+    switch (platform) {
+        case "darwin":
+            return path.join(home, "Library", "Caches", "samurai", "browsers");
+        case "win32":
+            return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "samurai", "browsers");
+        default:
+            return path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "samurai", "browsers");
+    }
+}

package/dist/browsers/downloader.d.ts

@@ -0,0 +1,23 @@
+/** Written into a build folder once its download and unpack finished; a folder without it is unfinished */
+export declare const COMPLETE_MARKER = ".samurai-complete";
+/** One build folder in the cache, as the downloader names it ("firefox", "chrome", "chromedriver") */
+export interface CachedBuild {
+    browser: string;
+    buildId: string;
+    dir: string;
+}
+/** What the store needs to fetch and find builds; tests pass a fake */
+export interface Downloader {
+    /** undefined: no builds exist for this OS and architecture */
+    platform(): string | undefined;
+    /** The folder a build is, or would be, unpacked into */
+    installDir(cacheDir: string, browser: string, buildId: string): string;
+    executablePath(cacheDir: string, browser: string, buildId: string): string;
+    install(cacheDir: string, browser: string, buildId: string, onProgress?: (done: number, total: number) => void): Promise<void>;
+    uninstall(cacheDir: string, browser: string, buildId: string): void;
+    /** Removes a build's folder (its marker first) and any archive a killed download left behind */
+    clean(cacheDir: string, browser: string, buildId: string): void;
+    list(cacheDir: string): CachedBuild[];
+}
+/** Downloads from Mozilla and Google with @puppeteer/browsers; `baseUrl` (tests only) points it elsewhere */
+export declare function puppeteerDownloader(baseUrl?: string | undefined): Downloader;

package/dist/browsers/downloader.js

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { Browser as PuppeteerBrowser, Cache, detectBrowserPlatform, install, } from "@puppeteer/browsers";
+/** Written into a build folder once its download and unpack finished; a folder without it is unfinished */
+export const COMPLETE_MARKER = ".samurai-complete";
+/** Downloads from Mozilla and Google with @puppeteer/browsers; `baseUrl` (tests only) points it elsewhere */
+export function puppeteerDownloader(baseUrl = process.env.SAMURAI_BROWSERS_BASE_URL) {
+    const platform = () => {
+        const found = detectBrowserPlatform();
+        if (!found)
+            throw new Error(`No browser downloads for ${process.platform} ${process.arch}`);
+        return found;
+    };
+    const as = (browser) => browser;
+    return {
+        platform: () => detectBrowserPlatform(),
+        installDir: (cacheDir, browser, buildId) => new Cache(cacheDir).installationDir(as(browser), platform(), buildId),
+        executablePath: (cacheDir, browser, buildId) => new Cache(cacheDir).computeExecutablePath({
+            browser: as(browser),
+            platform: platform(),
+            buildId,
+        }),
+        async install(cacheDir, browser, buildId, onProgress) {
+            await install({
+                cacheDir,
+                browser: as(browser),
+                buildId,
+                platform: platform(),
+                ...(onProgress && { downloadProgressCallback: onProgress }),
+                ...(baseUrl && { baseUrl }),
+            });
+        },
+        uninstall: (cacheDir, browser, buildId) => new Cache(cacheDir).uninstall(as(browser), platform(), buildId),
+        clean(cacheDir, browser, buildId) {
+            const cache = new Cache(cacheDir);
+            const dir = cache.installationDir(as(browser), platform(), buildId);
+            // The marker goes first: a removal that stops halfway leaves a folder that reads as missing
+            rmSync(path.join(dir, COMPLETE_MARKER), { force: true });
+            rmSync(dir, { recursive: true, force: true });
+            // The archive is downloaded next to the build folders, as <buildId>-<file>
+            const root = cache.browserRoot(as(browser));
+            if (!existsSync(root))
+                return;
+            for (const entry of readdirSync(root))
+                if (entry.startsWith(`${buildId}-`))
+                    rmSync(path.join(root, entry), { recursive: true, force: true });
+        },
+        list: (cacheDir) => new Cache(cacheDir)
+            .getInstalledBrowsers()
+            .map((b) => ({ browser: b.browser, buildId: b.buildId, dir: b.path })),
+    };
+}

package/dist/browsers/index.d.ts

@@ -0,0 +1,6 @@
+export { browsersCacheDir } from "./cache-dir.js";
+export type { CachedBuild, Downloader } from "./downloader.js";
+export { 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";

package/dist/browsers/index.js

@@ -0,0 +1,5 @@
+export { browsersCacheDir } from "./cache-dir.js";
+export { 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";

package/dist/browsers/overrides.d.ts

@@ -0,0 +1,17 @@
+import type { ManagedBrowser } from "./pins.js";
+/** A browser binary set on purpose, and where */
+export interface Override {
+    path: string;
+    from: "env" | "config";
+}
+/** Where the overrides come from; each defaults to the running process */
+export interface OverrideSources {
+    env?: Partial<NodeJS.ProcessEnv>;
+    /** `browserPaths` of samurai.config.ts */
+    browserPaths?: Partial<Record<ManagedBrowser, string>> | undefined;
+    /** What relative `browserPaths` resolve from */
+    projectDir?: string;
+}
+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

@@ -0,0 +1,15 @@
+import path from "node:path";
+export const ENV_PATH = {
+    firefox: "SAMURAI_FIREFOX_PATH",
+    chrome: "SAMURAI_CHROME_PATH",
+};
+/** The env variable, else the config's `browserPaths`; undefined: use the managed build */
+export function overrideOf(name, { env = process.env, browserPaths, projectDir = process.cwd(), } = {}) {
+    const fromEnv = env[ENV_PATH[name]];
+    if (fromEnv)
+        return { path: path.resolve(fromEnv), from: "env" };
+    const fromConfig = browserPaths?.[name];
+    if (fromConfig)
+        return { path: path.resolve(projectDir, fromConfig), from: "config" };
+    return undefined;
+}

package/dist/browsers/pins.d.ts

@@ -0,0 +1,16 @@
+/** The browser builds this framework version downloads and launches. Bumped by hand in a release */
+export declare const PINNED: {
+    readonly firefox: {
+        readonly buildId: "stable_158.0";
+        readonly label: "Firefox 158.0";
+    };
+    readonly chrome: {
+        readonly buildId: "155.0.8059.79";
+        readonly label: "Chrome for Testing 155.0.8059.79";
+    };
+};
+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 */
+export declare const LAUNCHABLE: readonly ManagedBrowser[];
+export declare function isManagedBrowser(name: string): name is ManagedBrowser;

package/dist/browsers/pins.js

@@ -0,0 +1,14 @@
+/** The browser builds this framework version downloads and launches. Bumped by hand in a release */
+export const PINNED = {
+    firefox: { buildId: "stable_158.0", label: "Firefox 158.0" },
+    chrome: {
+        buildId: "155.0.8059.79",
+        label: "Chrome for Testing 155.0.8059.79",
+    },
+};
+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"];
+export function isManagedBrowser(name) {
+    return Object.prototype.hasOwnProperty.call(PINNED, name);
+}

package/dist/browsers/resolve.d.ts

@@ -0,0 +1,26 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+import { type OverrideSources } from "./overrides.js";
+import { type ManagedBrowser } from "./pins.js";
+import { type BrowserStatus, type StoreOptions } from "./store.js";
+/** The browser a launch uses, and how to name it */
+export interface ResolvedBrowser {
+    executablePath: string;
+    /** "Firefox 158.0" for the managed build, else "Firefox" */
+    label: string;
+    /** The managed build's folder; undefined when an env or config path is used instead */
+    buildDir?: 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;
+/** The binary a launch uses; see `resolveBrowser` */
+export declare function resolveExecutable(name: ManagedBrowser, sources?: OverrideSources & StoreOptions): string;
+/** `resolveExecutable` for the active project */
+export declare function projectExecutable(name: ManagedBrowser): Promise<string>;
+/** `resolveBrowser` for the active project, with its config's `browserPaths` (none when the config can't be read) */
+export declare function projectBrowser(name: ManagedBrowser): Promise<ResolvedBrowser>;
+/** Every pinned browser's status for a project (default: the working directory); a config that can't be read gives no config overrides */
+export declare function browserStatus(options?: StoreOptions & {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+    env?: Partial<NodeJS.ProcessEnv>;
+}): Promise<BrowserStatus[]>;

package/dist/browsers/resolve.js

@@ -0,0 +1,56 @@
+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 { MANAGED_BROWSERS, PINNED } from "./pins.js";
+import { managedBuildDir, 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 override = overrideOf(name, sources);
+    if (!override)
+        return {
+            executablePath: managedExecutable(name, sources),
+            label: PINNED[name].label,
+            buildDir: managedBuildDir(name, sources),
+        };
+    if (!existsSync(override.path))
+        throw new Error(override.from === "env"
+            ? `${ENV_PATH[name]} points to a missing file: ${override.path}`
+            : `browserPaths.${name} in samurai.config.ts points to a missing file: ${override.path}`);
+    return {
+        executablePath: override.path,
+        label: name.charAt(0).toUpperCase() + name.slice(1),
+    };
+}
+/** The binary a launch uses; see `resolveBrowser` */
+export function resolveExecutable(name, sources = {}) {
+    return resolveBrowser(name, sources).executablePath;
+}
+/** `resolveExecutable` for the active project */
+export async function projectExecutable(name) {
+    return (await projectBrowser(name)).executablePath;
+}
+/** `resolveBrowser` for the active project, with its config's `browserPaths` (none when the config can't be read) */
+export async function projectBrowser(name) {
+    let browserPaths;
+    try {
+        browserPaths = await readConfig("browserPaths");
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return resolveBrowser(name, { browserPaths, projectDir: projectDir() });
+}
+/** Every pinned browser's status for a project (default: the working directory); a config that can't be read gives no config overrides */
+export async function browserStatus(options = {}) {
+    const dir = options.projectDir ?? process.cwd();
+    let browserPaths;
+    try {
+        browserPaths = (await projectConfig({ ...options, projectDir: dir }))
+            .browserPaths;
+    }
+    catch (err) {
+        logger.debug("Could not read browserPaths from config", { err });
+    }
+    return MANAGED_BROWSERS.map((name) => statusOf(name, { ...options, browserPaths, projectDir: dir }));
+}

package/dist/browsers/store.d.ts

@@ -0,0 +1,52 @@
+import { COMPLETE_MARKER, type Downloader } from "./downloader.js";
+import { type Override, type OverrideSources } from "./overrides.js";
+import { type ManagedBrowser } from "./pins.js";
+export { COMPLETE_MARKER };
+export declare class BrowserNotInstalledError extends Error {
+    readonly browser: ManagedBrowser;
+    readonly label: string;
+    constructor(browser: ManagedBrowser, label: string);
+}
+export interface StoreOptions {
+    /** Default: `browsersCacheDir()` */
+    cacheDir?: string;
+    /** Default: @puppeteer/browsers */
+    downloader?: Downloader;
+}
+export interface BrowserStatus {
+    name: ManagedBrowser;
+    label: string;
+    buildId: string;
+    /** unavailable: no download exists for this OS and architecture */
+    state: "installed" | "missing" | "unavailable";
+    executablePath?: string;
+    /** Whether the framework can launch it yet */
+    launchable: boolean;
+    /** A path set on purpose, which launches use instead of the managed build */
+    override?: Override;
+}
+export interface InstalledBuild {
+    name: ManagedBrowser;
+    buildId: string;
+    dir: string;
+    sizeBytes: number;
+    /** Pinned by this framework version */
+    pinned: boolean;
+}
+/**
+ * Downloads the pinned build unless it is complete already; returns its executable. The download goes into a
+ * private staging folder and is moved into place once complete, so two installs at once do not break each other.
+ */
+export declare function installBrowser(name: ManagedBrowser, options?: StoreOptions & {
+    onProgress?: (done: number, total: number) => void;
+}): Promise<string>;
+/** The pinned build of `name`: whether it is there, and any path set instead of it */
+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 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 */
+export declare function uninstallBrowser(name: ManagedBrowser, buildId?: string, options?: StoreOptions): void;
+/** Every Firefox and Chrome build in the cache, also those other framework versions pinned */
+export declare function listInstalled(options?: StoreOptions): InstalledBuild[];

package/dist/browsers/store.js

@@ -0,0 +1,170 @@
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { browsersCacheDir } from "./cache-dir.js";
+import { COMPLETE_MARKER, puppeteerDownloader, } from "./downloader.js";
+import { overrideOf, } from "./overrides.js";
+import { isManagedBrowser, LAUNCHABLE, PINNED, } from "./pins.js";
+export { COMPLETE_MARKER };
+/** Each install downloads into its own `<cache>/.staging-<random>/` and moves the finished build into place */
+const STAGING_PREFIX = ".staging-";
+/** A staging folder this old belongs to an install that was killed */
+const STALE_STAGING_MS = 24 * 60 * 60 * 1000;
+export class BrowserNotInstalledError extends Error {
+    constructor(browser, label) {
+        super(`${label} is not installed. Run: samurai browsers install ${browser}`);
+        this.browser = browser;
+        this.label = label;
+        this.name = "BrowserNotInstalledError";
+    }
+}
+const store = (options = {}) => ({
+    cacheDir: options.cacheDir ?? browsersCacheDir(),
+    downloader: options.downloader ?? puppeteerDownloader(),
+});
+/** The cache folders one managed browser consists of */
+const parts = (name) => name === "chrome" ? ["chrome", "chromedriver"] : [name];
+const complete = (dir) => existsSync(path.join(dir, COMPLETE_MARKER));
+function sizeOf(dir) {
+    let total = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        total += entry.isDirectory() ? sizeOf(full) : lstatSync(full).size;
+    }
+    return total;
+}
+/** Removes staging folders that killed installs left behind; best effort */
+function removeStaleStaging(cacheDir) {
+    if (!existsSync(cacheDir))
+        return;
+    for (const entry of readdirSync(cacheDir)) {
+        if (!entry.startsWith(STAGING_PREFIX))
+            continue;
+        const dir = path.join(cacheDir, entry);
+        try {
+            if (Date.now() - statSync(dir).mtimeMs > STALE_STAGING_MS)
+                rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // another process may be removing it too
+        }
+    }
+}
+/**
+ * Downloads the pinned build unless it is complete already; returns its executable. The download goes into a
+ * private staging folder and is moved into place once complete, so two installs at once do not break each other.
+ */
+export async function installBrowser(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const pin = PINNED[name];
+    if (!downloader.platform())
+        throw new Error(`${pin.label} has no download for ${process.platform} ${process.arch}`);
+    const dir = downloader.installDir(cacheDir, name, pin.buildId);
+    const exe = () => downloader.executablePath(cacheDir, name, pin.buildId);
+    if (complete(dir))
+        return exe();
+    let staging;
+    try {
+        removeStaleStaging(cacheDir);
+        mkdirSync(cacheDir, { recursive: true });
+        staging = mkdtempSync(path.join(cacheDir, STAGING_PREFIX));
+        for (const part of parts(name))
+            await downloader.install(staging, part, pin.buildId, part === name ? options.onProgress : undefined);
+        writeFileSync(path.join(downloader.installDir(staging, name, pin.buildId), COMPLETE_MARKER), new Date().toISOString());
+        // The part holding the marker moves last, so the build counts as complete only once every part is in place
+        for (const part of parts(name).reverse()) {
+            // Another install finished first
+            if (complete(dir))
+                return exe();
+            // An unfinished folder from an earlier attempt would block the move
+            downloader.clean(cacheDir, part, pin.buildId);
+            const target = downloader.installDir(cacheDir, part, pin.buildId);
+            mkdirSync(path.dirname(target), { recursive: true });
+            try {
+                renameSync(downloader.installDir(staging, part, pin.buildId), target);
+            }
+            catch (e) {
+                if (complete(dir))
+                    return exe();
+                throw e;
+            }
+        }
+    }
+    catch (e) {
+        throw new Error(`Could not download ${pin.label}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        if (staging)
+            rmSync(staging, { recursive: true, force: true });
+    }
+    return exe();
+}
+/** The pinned build of `name`: whether it is there, and any path set instead of it */
+export function statusOf(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const pin = PINNED[name];
+    const override = overrideOf(name, options);
+    const base = {
+        name,
+        label: pin.label,
+        buildId: pin.buildId,
+        launchable: LAUNCHABLE.includes(name),
+        ...(override && { override }),
+    };
+    if (!downloader.platform())
+        return { ...base, state: "unavailable" };
+    if (!complete(downloader.installDir(cacheDir, name, pin.buildId)))
+        return { ...base, state: "missing" };
+    return {
+        ...base,
+        state: "installed",
+        executablePath: downloader.executablePath(cacheDir, name, pin.buildId),
+    };
+}
+/** The pinned build's executable; throws BrowserNotInstalledError when it isn't complete */
+export function managedExecutable(name, options = {}) {
+    const status = statusOf(name, { ...options, env: {} });
+    if (status.state !== "installed")
+        throw new BrowserNotInstalledError(name, status.label);
+    return status.executablePath;
+}
+/** The folder the pinned build of `name` is, or would be, installed in */
+export function managedBuildDir(name, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    return downloader.installDir(cacheDir, name, PINNED[name].buildId);
+}
+/** Removes a build (default: the pinned one); Chrome takes its chromedriver along */
+export function uninstallBrowser(name, buildId = PINNED[name].buildId, options = {}) {
+    const { cacheDir, downloader } = store(options);
+    const root = path.resolve(cacheDir);
+    const dirs = parts(name).map((part) => ({
+        part,
+        dir: downloader.installDir(cacheDir, part, buildId),
+    }));
+    if (/[/\\]|\.\./.test(buildId) ||
+        dirs.some(({ dir }) => !path.resolve(dir).startsWith(root + path.sep)))
+        throw new Error(`Invalid build id "${buildId}"`);
+    for (const { part, dir } of dirs) {
+        if (!existsSync(dir))
+            continue;
+        // Without its marker a build that is only partly removed reads as missing
+        rmSync(path.join(dir, COMPLETE_MARKER), { force: true });
+        downloader.uninstall(cacheDir, part, buildId);
+    }
+}
+/** Every Firefox and Chrome build in the cache, also those other framework versions pinned */
+export function listInstalled(options = {}) {
+    const { cacheDir, downloader } = store(options);
+    return downloader
+        .list(cacheDir)
+        .filter((b) => isManagedBrowser(b.browser))
+        .map((b) => {
+        const name = b.browser;
+        return {
+            name,
+            buildId: b.buildId,
+            dir: b.dir,
+            sizeBytes: sizeOf(b.dir),
+            pinned: PINNED[name].buildId === b.buildId,
+        };
+    });
+}

package/dist/cli/args.d.ts

@@ -19,6 +19,8 @@ export declare function parseCommandLine(argv: string[]): {
         at?: string | undefined;
         new?: string | undefined;
         url?: string | undefined;
+        build?: string | undefined;
+        unused?: boolean | undefined;
         help?: boolean | undefined;
         version?: boolean | undefined;
     };

package/dist/cli/args.js

@@ -15,6 +15,8 @@ const FLAGS = {
     at: { type: "string" },
     new: { type: "string" },
     url: { type: "string" },
+    build: { type: "string" },
+    unused: { type: "boolean" },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" },
 };

package/dist/cli/browsers.d.ts

@@ -0,0 +1,6 @@
+import { type StoreOptions } from "../browsers/index.js";
+import type { Io } from "./main.js";
+export declare const BROWSERS_USAGE = "Usage:\n  samurai browsers [list]                        The pinned browsers and every build in the cache\n  samurai browsers install [firefox|chrome|all]  Download the pinned builds (default: all)\n  samurai browsers uninstall <name> [--build <id>]\n                                                 Remove a build (default: the pinned one)\n  samurai browsers uninstall --unused            Remove builds this framework version doesn't pin\n";
+export declare function formatBytes(n: number): string;
+/** `samurai browsers …`; `options` is for tests. The cache folder and download host follow `io.env` */
+export declare function browsersCommand(argv: string[], io: Io, options?: StoreOptions): Promise<number>;

package/dist/cli/browsers.js

@@ -0,0 +1,119 @@
+import { browsersCacheDir, browserStatus, installBrowser, isManagedBrowser, listInstalled, MANAGED_BROWSERS, PINNED, uninstallBrowser, } from "../browsers/index.js";
+import { puppeteerDownloader } from "../browsers/downloader.js";
+import { parseCommandLine } from "./args.js";
+export const BROWSERS_USAGE = `Usage:
+  samurai browsers [list]                        The pinned browsers and every build in the cache
+  samurai browsers install [firefox|chrome|all]  Download the pinned builds (default: all)
+  samurai browsers uninstall <name> [--build <id>]
+                                                 Remove a build (default: the pinned one)
+  samurai browsers uninstall --unused            Remove builds this framework version doesn't pin
+`;
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+class UnknownBrowser extends Error {
+}
+function names(arg) {
+    if (arg === undefined || arg === "all")
+        return [...MANAGED_BROWSERS];
+    if (!isManagedBrowser(arg))
+        throw new UnknownBrowser(arg);
+    return [arg];
+}
+async function list(io, store) {
+    for (const s of await browserStatus({ ...store, env: io.env })) {
+        const state = s.override
+            ? `uses ${s.override.path} (${s.override.from === "env" ? "environment variable" : "samurai.config.ts"})`
+            : s.state === "installed"
+                ? "installed"
+                : s.state === "missing"
+                    ? "not installed"
+                    : "no download for this computer";
+        io.out(`${s.label.padEnd(36)} ${state}\n`);
+    }
+    const other = listInstalled(store).filter((b) => !b.pinned);
+    if (other.length > 0) {
+        io.out("\nOther builds in the cache:\n");
+        for (const b of other)
+            io.out(`  ${b.name} ${b.buildId}  ${formatBytes(b.sizeBytes)}\n`);
+    }
+}
+async function install(io, targets, store) {
+    const baseUrl = io.env.SAMURAI_BROWSERS_BASE_URL;
+    if (baseUrl)
+        io.out(`Downloading from ${baseUrl}\n`);
+    for (const name of targets) {
+        const label = PINNED[name].label;
+        let shown = -1;
+        const exe = await installBrowser(name, {
+            ...store,
+            onProgress: (done, total) => {
+                const percent = total > 0 ? Math.floor((done / total) * 100) : 0;
+                if (io.color) {
+                    io.out(`\r${label}: ${percent}%`);
+                }
+                else if (percent >= shown + 10 ||
+                    (percent === 100 && shown !== 100)) {
+                    shown = percent;
+                    io.out(`${label}: ${percent}%\n`);
+                }
+            },
+        });
+        if (io.color)
+            io.out("\n");
+        io.out(`${label} installed at ${exe}\n`);
+    }
+}
+/** `samurai browsers …`; `options` is for tests. The cache folder and download host follow `io.env` */
+export async function browsersCommand(argv, io, options = {}) {
+    const store = {
+        cacheDir: options.cacheDir ?? browsersCacheDir(io.env),
+        downloader: options.downloader ??
+            puppeteerDownloader(io.env.SAMURAI_BROWSERS_BASE_URL),
+    };
+    const { values, positionals } = parseCommandLine(argv);
+    const [sub = "list", target] = positionals;
+    try {
+        if (sub === "list") {
+            await list(io, store);
+            return 0;
+        }
+        if (sub === "install") {
+            await install(io, names(target), store);
+            return 0;
+        }
+        if (sub === "uninstall") {
+            if (values.unused) {
+                for (const b of listInstalled(store).filter((b) => !b.pinned)) {
+                    uninstallBrowser(b.name, b.buildId, store);
+                    io.out(`removed ${b.name} ${b.buildId}\n`);
+                }
+                io.out("Projects on other framework versions may still use the removed builds.\n");
+                return 0;
+            }
+            if (target === undefined || target === "all") {
+                io.err(`Which browser? \n\n${BROWSERS_USAGE}`);
+                return 2;
+            }
+            const [name] = names(target);
+            uninstallBrowser(name, values.build, store);
+            io.out(`removed ${name} ${values.build ?? PINNED[name].buildId}\n`);
+            return 0;
+        }
+        io.err(`Unknown browsers command "${sub}"\n\n${BROWSERS_USAGE}`);
+        return 2;
+    }
+    catch (e) {
+        if (e instanceof UnknownBrowser) {
+            io.err(`Unknown browser "${e.message}". Choose firefox, chrome or all.\n`);
+            return 1;
+        }
+        throw e;
+    }
+}

package/dist/cli/main.d.ts

@@ -1,4 +1,4 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
 export interface Io {
     out: (text: string) => void;
     err: (text: string) => void;

package/dist/cli/main.js

@@ -4,6 +4,7 @@ import { recordSpec } from "../recorder/index.js";
 import { listTests, runTests } from "../runner/run.js";
 import { stepToSource } from "../steps/index.js";
 import { ConsoleReporter } from "./console-reporter.js";
+import { browsersCommand } from "./browsers.js";
 import { flowCommand } from "./flow.js";
 import { initProject } from "./init.js";
 export const USAGE = `samurai: browser tests over WebDriver BiDi
@@ -14,6 +15,7 @@ Usage:
   samurai record <spec>       Open a browser and record what you do into a spec file
   samurai init [folder]       Scaffold a project: config, an example test, .env.example
   samurai flow <command>      List, check and run the flows in ./flows (see below)
+  samurai browsers [command]  List, install and remove the browsers SAMURAI launches
 
 Options for run and list:
   --env <name>                Environment to run against (or SAMURAI_ENV)
@@ -48,6 +50,12 @@ samurai flow:
   Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported
   Run \`samurai flow\` alone for the details.
 
+samurai browsers:
+  list                        The pinned browsers and every build in the cache (the default)
+  install [firefox|chrome|all]
+                              Download the pinned builds (default: all)
+  uninstall <name> [--build <id>] | --unused
+
 Run it in the project folder, the one holding samurai.config.ts.
 `;
 function version() {
@@ -72,13 +80,15 @@ export async function main(argv, io) {
         }
         if (command === "flow")
             return await flowCommand(rest, io);
+        if (command === "browsers")
+            return await browsersCommand(rest, io);
         if (command === "init") {
             const { written, skipped } = initProject(positionals[0] ?? ".");
             for (const file of written)
                 io.out(`created ${file}\n`);
             for (const file of skipped)
                 io.out(`kept    ${file} (already there)\n`);
-            io.out("\nNext: install the dependencies, then `samurai run`.\n");
+            io.out("\nNext: install the dependencies, then `samurai browsers install firefox`, then `samurai run`.\n");
             return 0;
         }
         if (command === "record") {

package/dist/recorder/session.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Browser } from "../browser/browser.js";
+import { ensureWarm } from "../browser/warm-up.js";
 import { projectDir } from "../config/config.js";
 import { withProject } from "../runner/project.js";
 import { parseSpec } from "../steps/parse.js";
@@ -52,6 +53,9 @@ export async function recordSpec(options) {
         if (source === undefined && options.create === undefined) {
             throw new Error(`${options.file} does not exist; give a title with --new to create it`);
         }
+        // Before the spec is touched: a recording without its browser changes nothing
+        await ensureWarm("firefox", { port: options.port ?? 9223 }, options.signal);
+        options.signal?.throwIfAborted();
         source ??= "";
         if (options.create !== undefined &&
             !parseSpec(source).some((t) => t.name === options.create)) {

package/dist/runner/test-runner.js

@@ -3,6 +3,7 @@ import { glob } from "node:fs/promises";
 import path from "path";
 import { pathToFileURL } from "url";
 import { Browser } from "../browser/browser.js";
+import { ensureWarm } from "../browser/warm-up.js";
 import { loadConfig, projectDir, readConfig } from "../config/config.js";
 import logger from "../logger/index.js";
 import { assertModuleProject } from "./module-type.js";
@@ -115,6 +116,10 @@ export default class TestRunner {
             ...(onEvent && { onEvent }),
         });
         const selected = await this.register();
+        // A missing browser is one clear error before the run, not a failure per test; a fresh build's slow
+        // first start happens here, outside any test's timeout
+        if (selected.length > 0)
+            await ensureWarm((await readConfig("browser")) ?? "firefox", { port: this.options.port ?? 9223 }, signal);
         reporter.onStart(selected.length);
         for (const test of selected) {
             if (signal?.aborted) {

package/dist/transport/bidi-connection.d.ts

@@ -1,5 +1,7 @@
 import type { BiDiCommands, BiDiEvents } from "../types/bidi.js";
 import { type EventName, type Subscription, type SubscribeOptions } from "./subscriptions.js";
+/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
+export declare const DEFAULT_COMMAND_TIMEOUT = 30000;
 export interface ConnectorOptions {
     /** @default 30000 */
     commandTimeout?: number;

package/dist/transport/bidi-connection.js

@@ -4,7 +4,7 @@ import { WaitTimeoutError } from "../wait/wait-until.js";
 import { BiDiError } from "./bidi-error.js";
 import { SubscriptionManager, } from "./subscriptions.js";
 /** Time (ms) a command may wait for its reply before it fails with code "timeout" */
-const DEFAULT_COMMAND_TIMEOUT = 30000;
+export const DEFAULT_COMMAND_TIMEOUT = 30000;
 /**
  * The connection to the browser is gone (the browser exited or was closed, or the socket dropped). Commands that
  * were waiting fail with it, and so does every command sent afterwards: a closed socket would swallow them silently.

package/dist/types/config.d.ts

@@ -49,6 +49,11 @@ export interface SamuraiTestConfig {
    * Is overwritten by the 'browser' in a group's config
    */
   browser?: SupportedBrowser;
+  /**
+   * Browser binaries to launch instead of the builds SAMURAI downloads, relative to the project.
+   * `SAMURAI_FIREFOX_PATH` / `SAMURAI_CHROME_PATH` win over these.
+   */
+  browserPaths?: { firefox?: string; chrome?: string };
   /**
    * The timeout (in ms) to use for all tests
    * @default 30000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {
@@ -24,6 +24,10 @@
       "types": "./dist/cli/init.d.ts",
       "default": "./dist/cli/init.js"
     },
+    "./browsers": {
+      "types": "./dist/browsers/index.d.ts",
+      "default": "./dist/browsers/index.js"
+    },
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "default": "./dist/browser/index.js"
@@ -65,6 +69,7 @@
     "tsx": "^4.21.0"
   },
   "dependencies": {
+    "@puppeteer/browsers": "^3.2.4",
     "typescript": "^6.0.2",
     "winston": "^3.19.0"
   },