@itmetsam/samurai-framework 0.5.0 → 0.7.0

package/README.md

@@ -20,16 +20,16 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
-- **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)).
+- **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](docs/recorder.md)). The Electron app that ties them together lives in a separate repository (see the [roadmap](docs/roadmap.md)).
 
-> **Status:** early. Firefox only, 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
 
@@ -119,7 +119,7 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
 | [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
 | [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
-| [Steps and the recorder](docs/recorder.md)                   | The step codec and the recording engine                                                               |
+| [Steps and the recorder](docs/recorder.md)                   | The step codec, the recording engine and the recorder toolbar                                         |
 | [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
 | [Contributing](docs/contributing.md)                         | Project layout, running the framework's own tests, conventions                                        |
 | [Roadmap](docs/roadmap.md)                                   | What is built and what is still open                                                                  |

package/bin/samurai.mjs

@@ -1,4 +1,29 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Specs import the framework from their project. A global (or linked) samurai must run that same copy, or the specs
+// register their tests in the project's copy and this one finds none
+const own = realpathSync(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), ".."),
+);
+let local;
+try {
+  local = path.dirname(
+    createRequire(path.join(process.cwd(), "package.json")).resolve(
+      "@itmetsam/samurai-framework/package.json",
+    ),
+  );
+} catch {
+  local = undefined;
+}
+if (local !== undefined && realpathSync(local) !== own) {
+  // That copy's binary runs the command and exits
+  await import(pathToFileURL(path.join(local, "bin/samurai.mjs")).href);
+}
+
 // Quiet the framework's console logging unless the caller asked for more; the log files keep everything
 process.env.SAMURAI_LOG_LEVEL ??= "warn";
 

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/evidence.d.ts

@@ -0,0 +1,19 @@
+/** A screenshot name as a file name: letters, digits, - and _ (the rest becomes -) */
+export declare function cleanName(name: string): string;
+/** Where a run (or one test) saves named screenshots, and the ones it saved */
+export declare class Evidence {
+    private readonly resultDir;
+    private readonly testDir?;
+    readonly screenshots: {
+        name: string;
+        path: string;
+    }[];
+    private readonly used;
+    constructor(resultDir: string, testDir?: string | undefined);
+    /** The file for the next screenshot called `name` (`.jpg` for a jpeg, else `.png`); a repeat gets -2, -3, … */
+    fileFor(name: string, type?: "png" | "jpeg"): {
+        file: string;
+        name: string;
+        path: string;
+    };
+}

package/dist/browser/evidence.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+/** A screenshot name as a file name: letters, digits, - and _ (the rest becomes -) */
+export function cleanName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned === "" ? "screenshot" : cleaned;
+}
+/** Where a run (or one test) saves named screenshots, and the ones it saved */
+export class Evidence {
+    constructor(resultDir, testDir) {
+        this.resultDir = resultDir;
+        this.testDir = testDir;
+        this.screenshots = [];
+        this.used = new Set();
+    }
+    /** The file for the next screenshot called `name` (`.jpg` for a jpeg, else `.png`); a repeat gets -2, -3, … */
+    fileFor(name, type = "png") {
+        const base = cleanName(name);
+        let unique = base;
+        for (let n = 2; this.used.has(unique); n++)
+            unique = `${base}-${n}`;
+        this.used.add(unique);
+        const relative = [
+            "screenshots",
+            ...(this.testDir ? this.testDir.split("/") : []),
+            `${unique}.${type === "jpeg" ? "jpg" : "png"}`,
+        ].join("/");
+        const entry = {
+            file: path.join(this.resultDir, ...relative.split("/")),
+            name: unique,
+            path: relative,
+        };
+        this.screenshots.push({ name: entry.name, path: entry.path });
+        return entry;
+    }
+}

package/dist/browser/page.d.ts

@@ -9,6 +9,7 @@ import { type EmulationOptions } from "./emulation.js";
 import { Download } from "./download.js";
 import { FileChooser } from "./file-chooser.js";
 import { type ScreenshotOptions } from "./screenshot.js";
+import { Evidence } from "./evidence.js";
 import { type ConsoleMessage, type LogRecord, type PageError } from "./page-logs.js";
 import { type RouteHandler } from "../network/router.js";
 import { Response } from "../network/response.js";
@@ -182,6 +183,11 @@ export default class Page {
      *  await page.screenshot({ path: "out/home.png", fullPage: true });
      */
     screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    private evidence;
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence: Evidence | undefined): void;
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    waitForTimeout(ms: number): Promise<void>;
     /** Renders the page as a PDF and returns it (also written to `options.path`) */
     pdf(options?: PdfOptions): Promise<Buffer>;
     /** The browser context (cookies, storage) this page belongs to */

package/dist/browser/page.js

@@ -1,7 +1,8 @@
 import Locator, {} from "../locator/locator.js";
 import { cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
 import EventEmitter from "node:events";
-import { readConfig } from "../config/config.js";
+import path from "node:path";
+import { projectDir, readConfig } from "../config/config.js";
 import { peekRunSettings } from "../config/run-settings.js";
 import logger from "../logger/index.js";
 import { NetworkTracker, } from "../network/network-tracker.js";
@@ -13,7 +14,8 @@ import { applyEmulation } from "./emulation.js";
 import { Download, DownloadTracker } from "./download.js";
 import { FileChooser, FileChooserTracker } from "./file-chooser.js";
 import { DownloadWaitTimeoutError, FileChooserTimeoutError, } from "./page-wait.js";
-import { takeScreenshot } from "./screenshot.js";
+import { takeScreenshot, writeOutput, } from "./screenshot.js";
+import { Evidence } from "./evidence.js";
 import { PageLogs, } from "./page-logs.js";
 import { Router } from "../network/router.js";
 import { DataCollector, ResponseBodyUnavailableError, } from "../network/data-collector.js";
@@ -405,7 +407,22 @@ export default class Page {
      */
     async screenshot(options = {}) {
         this.assertOpen();
-        return takeScreenshot(this.biDiConnector, this.id, options);
+        const image = await takeScreenshot(this.biDiConnector, this.id, options);
+        if (options.name !== undefined) {
+            const evidence = this.evidence ?? new Evidence(path.join(projectDir(), "result"));
+            await writeOutput(evidence.fileFor(options.name, options.type).file, image);
+        }
+        return image;
+    }
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence) {
+        this.evidence = evidence;
+    }
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    async waitForTimeout(ms) {
+        if (!Number.isFinite(ms) || ms < 0)
+            throw new RangeError(`waitForTimeout needs 0 or more milliseconds, got ${ms}`);
+        await new Promise((resolve) => setTimeout(resolve, ms));
     }
     /** Renders the page as a PDF and returns it (also written to `options.path`) */
     async pdf(options = {}) {

package/dist/browser/screenshot.d.ts

@@ -11,6 +11,8 @@ export interface ScreenshotOptions {
         width: number;
         height: number;
     };
+    /** Also save the image as run evidence under this name (see the Page API docs) */
+    name?: string;
     /** @default "png" */
     type?: "png" | "jpeg";
     /** 0 to 100, jpeg only */

package/dist/browser/screenshot.js

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 const MIME = { png: "image/png", jpeg: "image/jpeg" };
 /** The `format` of a capture command; validates the type/quality combination */
-function imageFormat({ type, quality }) {
+function imageFormat({ type, quality, }) {
     if (quality !== undefined) {
         if (type !== "jpeg")
             throw new RangeError("screenshot(): quality only applies to jpeg");
@@ -12,7 +12,10 @@ function imageFormat({ type, quality }) {
     }
     if (type === undefined)
         return undefined;
-    return { type: MIME[type], ...(quality !== undefined && { quality: quality / 100 }) };
+    return {
+        type: MIME[type],
+        ...(quality !== undefined && { quality: quality / 100 }),
+    };
 }
 /**
  * Captures the page (or, with `element`, that element) and returns the image. Writes it to `options.path` too.

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[]>;