@itmetsam/samurai-framework 0.4.0 → 0.6.0

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

@@ -1,10 +1,12 @@
-import { type FlowFile } from "../flows/core/index.js";
+import { type AnyNodeDefinition, type FlowFile } from "../flows/core/index.js";
 import { type FlowEvent } from "../flows/run/index.js";
 export interface FlowReporterOptions {
     flow: FlowFile;
     write: (text: string) => void;
     /** Colour with ANSI codes */
     color: boolean;
+    /** Definitions of the project's steps, for their labels. @default the built-in steps */
+    steps?: readonly AnyNodeDefinition[];
 }
 /** Prints a flow run for a person: one line per node as it ends, then a count. Start and End are not listed. */
 export declare class FlowReporter {
@@ -12,8 +14,9 @@ export declare class FlowReporter {
     private readonly paint;
     private readonly nodes;
     private readonly flow;
+    private readonly steps;
     private started;
-    constructor({ flow, write, color }: FlowReporterOptions);
+    constructor({ flow, write, color, steps }: FlowReporterOptions);
     private shapeOf;
     private listed;
     private nameOf;

package/dist/cli/flow-reporter.js

@@ -5,8 +5,9 @@ const took = (ms) => ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(
 const SKIPPED_BY_SHAPE = new Set(["start", "end"]);
 /** Prints a flow run for a person: one line per node as it ends, then a count. Start and End are not listed. */
 export class FlowReporter {
-    constructor({ flow, write, color }) {
+    constructor({ flow, write, color, steps }) {
         this.started = Date.now();
+        this.steps = steps ?? STEP_NODES;
         this.flow = flow;
         this.write = write;
         this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
@@ -29,7 +30,7 @@ export class FlowReporter {
             label = nodeDef(node.kind).label;
         }
         catch {
-            label = STEP_NODES.find((d) => d.kind === node.kind)?.label ?? node.kind;
+            label = this.steps.find((d) => d.kind === node.kind)?.label ?? node.kind;
         }
         const base = node.title || label;
         const wrote = result.wrote ? Object.keys(result.wrote) : [];

package/dist/cli/flow.d.ts

@@ -1,4 +1,4 @@
 import type { Io } from "./main.js";
-export declare const FLOW_USAGE = "Usage:\n  samurai flow list [--json]                    List the flows in ./flows\n  samurai flow check [<flow>...] [options]      Check flows without running them (all flows when none is given)\n  samurai flow run <flow>... [options]          Run flows, in the order given\n  samurai flow run --all [options]              Run every flow in ./flows, in file name order\n\nA flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.\n\nOptions for check and run:\n  --env <name>                Environment to use (or SAMURAI_ENV)\n  --allow-unsupported         Skip nodes that can't run yet (HTTP request, ...) instead of refusing the flow\n  --json                      Machine-readable output: JSON lines for run, one array for check and 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  --port <n>                  Browser debugging port (default 9223)\n\nEach run writes result/flows/<id>.json.\nExit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,\n2 for a usage, configuration or flow-file error, or a flow that has errors (nothing ran).\n";
+export declare const FLOW_USAGE = "Usage:\n  samurai flow list [--json]                    List the flows in ./flows\n  samurai flow check [<flow>...] [options]      Check flows without running them (all flows when none is given)\n  samurai flow run <flow>... [options]          Run flows, in the order given\n  samurai flow run --all [options]              Run every flow in ./flows, in file name order\n\nA flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.\n\nOptions for check and run:\n  --env <name>                Environment to use (or SAMURAI_ENV)\n  --allow-unsupported         Skip nodes whose kind has no handler instead of refusing the flow (every built-in kind runs)\n  --json                      Machine-readable output: JSON lines for run, one array for check and 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  --port <n>                  Browser debugging port (default 9223)\n\nEach run writes result/flows/<id>.json.\nExit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,\n2 for a usage, configuration or flow-file error, or a flow that has errors (nothing ran).\n";
 /** `samurai flow ...`: `argv` is what follows `flow`. Returns the exit code */
 export declare function flowCommand(argv: string[], io: Io): Promise<number>;

package/dist/cli/flow.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
 import { FlowReporter } from "./flow-reporter.js";
+import { projectSteps } from "../flows/steps/index.js";
 import {} from "../flows/core/index.js";
 import { FLOW_SUFFIX, FlowCheckError, FlowReportBuilder, checkFlowInProject, flowsDir, listFlows, readFlow, readFlowPath, runFlowInProject, writeFlowReport, } from "../flows/run/index.js";
 export const FLOW_USAGE = `Usage:
@@ -13,7 +14,7 @@ A flow is an id (flows/<id>.flow.json) or a path to a .flow.json file.
 
 Options for check and run:
   --env <name>                Environment to use (or SAMURAI_ENV)
-  --allow-unsupported         Skip nodes that can't run yet (HTTP request, ...) instead of refusing the flow
+  --allow-unsupported         Skip nodes whose kind has no handler instead of refusing the flow (every built-in kind runs)
   --json                      Machine-readable output: JSON lines for run, one array for check and list
 
 Options for run:
@@ -136,6 +137,7 @@ async function run(refs, io, options) {
             io.err(`${flow.id} can't run:\n${problemLines(io, described)}Nothing was run.\n`);
         return 2;
     };
+    const { nodes: steps } = await projectSteps({ projectDir });
     // Several flows: refuse them all before the first one runs
     if (flows.length > 1) {
         for (const flow of flows) {
@@ -159,7 +161,7 @@ async function run(refs, io, options) {
         const builder = new FlowReportBuilder(flow);
         const human = options.json
             ? undefined
-            : new FlowReporter({ flow, write: io.out, color: io.color });
+            : new FlowReporter({ flow, write: io.out, color: io.color, steps });
         if (flows.indexOf(flow) > 0 && !options.json)
             io.out("\n");
         let summary;

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

@@ -19,6 +19,11 @@ export declare function projectDir(): string;
 export declare function browsersDir(): string;
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export declare function loadConfig(): Promise<SamuraiTestConfig>;
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export declare function projectConfig(options: {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<SamuraiTestConfig>;
 export declare function readConfig<K extends keyof SamuraiTestConfig>(key: K): Promise<SamuraiTestConfig[K]>;
 export declare function defineConfig(config: SamuraiTestConfig): SamuraiTestConfig;
 export {};

package/dist/config/config.js

@@ -32,6 +32,19 @@ export async function loadConfig() {
     }
     return config.default;
 }
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export async function projectConfig(options) {
+    if (options.config)
+        return options.config;
+    const previous = activeProject;
+    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
+    try {
+        return await loadConfig();
+    }
+    finally {
+        setActiveProject(previous);
+    }
+}
 export async function readConfig(key) {
     const value = (await loadConfig())[key];
     logger.debug("Resolved config value: ", { value });

package/dist/flows/core/steps.js

@@ -1,7 +1,11 @@
 import { getPath } from "./nodes/path.js";
 export const STEP_KIND = /^[a-z][a-z0-9-]*$/;
 /** A node's own result fields: an output can't take these names */
-export const RESERVED_OUTPUTS = ["status", "durationMs", "error"];
+export const RESERVED_OUTPUTS = [
+    "status",
+    "durationMs",
+    "error",
+];
 const TITLE_FIELDS = [
     { path: "title", type: "text", label: "Title" },
     { path: "subtitle", type: "text", label: "Description" },
@@ -10,7 +14,11 @@ const empty = (value) => value === undefined || (typeof value === "string" && va
 /** Problems with `node`'s values against the fields' rules, as "Label: message" */
 export function fieldProblems(fields, node, label) {
     const problems = [];
-    const add = (message) => problems.push({ level: "error", nodeId: node.id, message: `${label}: ${message}` });
+    const add = (message) => problems.push({
+        level: "error",
+        nodeId: node.id,
+        message: `${label}: ${message}`,
+    });
     for (const f of fields) {
         const name = f.label ?? f.path;
         const value = getPath(node, f.path);
@@ -24,7 +32,10 @@ export function fieldProblems(fields, node, label) {
             if (f.max !== undefined && value > f.max)
                 add(`${name} must be at most ${f.max}.`);
         }
-        if (f.pattern && typeof value === "string" && value !== "" && !new RegExp(f.pattern).test(value))
+        if (f.pattern &&
+            typeof value === "string" &&
+            value !== "" &&
+            !new RegExp(f.pattern).test(value))
             add(f.patternMessage ?? `${name} doesn't match ${f.pattern}.`);
     }
     return problems;

package/dist/flows/run/index.d.ts

@@ -5,4 +5,5 @@ export type { Handler, HandlerRun, Outcome } from "./handlers/index.js";
 export { runFlow, type RunFlowOptions } from "./run.js";
 export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
 export * from "./report.js";
+export { projectSteps, type StepSet } from "../steps/set.js";
 export { FlowCheckError, checkFlowInProject, chooseEnvironment, runFlowInProject, type RunFlowInProjectOptions, } from "./project.js";

package/dist/flows/run/index.js

@@ -4,4 +4,5 @@ export { HANDLERS } from "./handlers/index.js";
 export { runFlow } from "./run.js";
 export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
 export * from "./report.js";
+export { projectSteps } from "../steps/set.js";
 export { FlowCheckError, checkFlowInProject, chooseEnvironment, runFlowInProject, } from "./project.js";

package/dist/flows/run/project.js

@@ -1,12 +1,12 @@
 import path from "node:path";
-import { loadConfig, setActiveProject } from "../../config/config.js";
+import { projectConfig } from "../../config/config.js";
 import { checkFlow, withKeys, } from "../core/index.js";
-import { DEFAULT_SRC_DIR, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
+import { DEFAULT_SRC_DIR, realPath, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
 import { withProject } from "../../runner/project.js";
 import { runTests } from "../../runner/run.js";
 import TestRunner from "../../runner/test-runner.js";
 import { readFlow } from "./files.js";
-import { STEP_NODES } from "../steps/catalog.js";
+import { projectSteps } from "../steps/set.js";
 import { HANDLERS } from "./handlers/index.js";
 import { runFlow } from "./run.js";
 /** The flow has errors; nothing was run */
@@ -17,18 +17,6 @@ export class FlowCheckError extends Error {
         this.name = "FlowCheckError";
     }
 }
-/** Reads the project's config without keeping the project active (`withProject` is one at a time) */
-async function configOf(options) {
-    if (options.config)
-        return options.config;
-    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
-    try {
-        return await loadConfig();
-    }
-    finally {
-        setActiveProject(undefined);
-    }
-}
 /** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
 export function chooseEnvironment(config, flow, option) {
     const names = Object.keys(config.environments ?? {});
@@ -46,7 +34,8 @@ async function prepare(options) {
     const flow = withKeys(options.flow ?? (await readFlow(projectDir, options.flowId)));
     const unsupported = options.unsupported ?? "fail";
     // Config, environment, tests and groups (one project session, then it ends)
-    const config = await configOf({ ...options, projectDir });
+    const config = await projectConfig({ ...options, projectDir });
+    const steps = await projectSteps({ config });
     const name = chooseEnvironment(config, flow, options.environment);
     const environment = {
         name,
@@ -56,7 +45,9 @@ async function prepare(options) {
                 : {}),
         },
     };
-    const srcDir = path.resolve(projectDir, config.srcDir ?? DEFAULT_SRC_DIR);
+    // Real paths, like the registered test files
+    const realDir = realPath(projectDir);
+    const srcDir = realPath(path.resolve(realDir, config.srcDir ?? DEFAULT_SRC_DIR));
     const { tests, groups } = await withProject({
         projectDir,
         config,
@@ -70,22 +61,26 @@ async function prepare(options) {
             name: t.name,
             relative: toPosix(path.relative(srcDir, t.file)),
         }));
-        const groups = resolveGroups(config, tests.map((t) => ({ file: t.relative, name: t.name })), projectDir, srcDir);
+        const groups = resolveGroups(config, tests.map((t) => ({ file: t.relative, name: t.name })), realDir, srcDir);
         return { tests, groups };
     });
     const problems = checkFlow(flow, {
         tests: tests.map((t) => t.id),
         groups: groups.map((g) => g.name),
         environment,
-        handled: new Set(Object.keys(HANDLERS)),
+        handled: new Set([
+            ...Object.keys(HANDLERS),
+            ...Object.keys(steps.handlers),
+        ]),
         unsupported,
-        nodes: STEP_NODES,
+        nodes: steps.nodes,
     });
     return {
         projectDir,
         flow,
         unsupported,
         config,
+        steps,
         name,
         environment,
         tests,
@@ -107,7 +102,7 @@ export async function checkFlowInProject(options) {
  * its tests through `runTests`, one after the other. One at a time per process.
  */
 export async function runFlowInProject(options) {
-    const { projectDir, flow, unsupported, config, name, environment, tests, groups, problems, } = await prepare(options);
+    const { projectDir, flow, unsupported, config, steps, name, environment, tests, groups, problems, } = await prepare(options);
     const errors = problems.filter((p) => p.level === "error");
     if (errors.length)
         throw new FlowCheckError(errors);
@@ -136,6 +131,8 @@ export async function runFlowInProject(options) {
         ...(options.onEvent && { onEvent: options.onEvent }),
         ...(options.sleep && { sleep: options.sleep }),
         unsupported,
+        handlers: { ...HANDLERS, ...steps.handlers },
+        nodes: steps.nodes,
         runTests: async ({ tests, onEvent, signal }) => {
             const summary = await run({
                 projectDir,