@itmetsam/samurai-framework 0.10.0 → 0.12.0

package/dist/browser/pdf.d.ts

@@ -46,7 +46,7 @@ declare const PAPER: {
         readonly height: 14.8;
     };
 };
-export type PaperFormat = keyof typeof PAPER;
+type PaperFormat = keyof typeof PAPER;
 export interface PdfOptions {
     /** Also write the PDF here (folders are created) */
     path?: string;

package/dist/browser/session.d.ts

@@ -0,0 +1,16 @@
+import { type BiDiConnector } from "../transport/bidi-connection.js";
+/** 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>;
+/**
+ * Stops what a failed launch started. A browser left running holds the profile (the next launch
+ * fails with "already open") and keeps the test process alive.
+ */
+export declare function abandonLaunch(browserProc: {
+    kill(): boolean;
+}, biDiConnector: {
+    kill(): void;
+} | undefined): void;

package/dist/browser/session.js

@@ -0,0 +1,32 @@
+import { DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
+import { BiDiError } from "../transport/bidi-error.js";
+import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+/** 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;
+    }
+}
+/**
+ * Stops what a failed launch started. A browser left running holds the profile (the next launch
+ * fails with "already open") and keeps the test process alive.
+ */
+export function abandonLaunch(browserProc, biDiConnector) {
+    biDiConnector?.kill();
+    browserProc.kill();
+}

package/dist/browser/viewport.d.ts

@@ -0,0 +1,19 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** The size a page gets unless config `use.viewport` says otherwise */
+export declare const DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+};
+/** A viewport as `page.setViewport` takes it: a size and optionally a device pixel ratio */
+export interface Viewport {
+    width: number;
+    height: number;
+    devicePixelRatio?: number;
+}
+/** Throws RangeError when the size or the ratio is not usable, before anything is sent */
+export declare function validateViewport({ width, height, devicePixelRatio, }: Viewport): void;
+/**
+ * Gives the context this size (and optionally this device pixel ratio); `null` puts the browser's own size back
+ * and waits until the page has really got it.
+ */
+export declare function applyViewport(connector: BiDiConnector, context: string, viewport: Viewport | null): Promise<void>;

package/dist/browser/viewport.js

@@ -0,0 +1,72 @@
+import { callFunction } from "../script/call-function.js";
+/** The size a page gets unless config `use.viewport` says otherwise */
+export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+/** Time (ms) without a `resize` event after which a viewport reset counts as done */
+const RESIZE_QUIET_TIME = 50;
+/** Time (ms) a viewport reset waits for a `resize` event that may never come (the size did not change) */
+const RESIZE_MAX_WAIT = 300;
+/** Throws RangeError when the size or the ratio is not usable, before anything is sent */
+export function validateViewport({ width, height, devicePixelRatio, }) {
+    for (const [name, value] of [
+        ["width", width],
+        ["height", height],
+    ]) {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new RangeError(`setViewport(): ${name} must be a positive integer, got ${value}`);
+        }
+    }
+    if (devicePixelRatio !== undefined &&
+        !(devicePixelRatio > 0 && Number.isFinite(devicePixelRatio))) {
+        throw new RangeError(`setViewport(): devicePixelRatio must be a positive number, got ${devicePixelRatio}`);
+    }
+}
+/**
+ * Gives the context this size (and optionally this device pixel ratio); `null` puts the browser's own size back
+ * and waits until the page has really got it.
+ */
+export async function applyViewport(connector, context, viewport) {
+    if (viewport === null) {
+        await untilResized(connector, context, () => connector.send("browsingContext.setViewport", {
+            context,
+            viewport: null,
+            devicePixelRatio: null,
+        }));
+        return;
+    }
+    validateViewport(viewport);
+    const { width, height, devicePixelRatio } = viewport;
+    await connector.send("browsingContext.setViewport", {
+        context,
+        viewport: { width, height },
+        ...(devicePixelRatio !== undefined && { devicePixelRatio }),
+    });
+}
+/**
+ * Runs `change`, then waits until the page has stopped resizing. Chrome answers a viewport reset before the window
+ * has its own size back, so a read right after it can still show the old size. The wait ends `RESIZE_QUIET_TIME`
+ * after the last `resize` event, and after `RESIZE_MAX_WAIT` when the size does not change at all (no event
+ * comes). Never fails: a page that cannot be watched is simply not waited for.
+ */
+async function untilResized(connector, context, change) {
+    const sandbox = { sandbox: "samurai-viewport" };
+    const watching = await callFunction(connector, context, `() => {
+        globalThis.__resized = new Promise((resolve) => {
+          let timer;
+          const finish = () => {
+            clearTimeout(timer);
+            removeEventListener("resize", onResize);
+            resolve();
+          };
+          const onResize = () => {
+            clearTimeout(timer);
+            timer = setTimeout(finish, ${RESIZE_QUIET_TIME});
+          };
+          addEventListener("resize", onResize);
+          timer = setTimeout(finish, ${RESIZE_MAX_WAIT});
+        });
+      }`, [], { ...sandbox, awaitPromise: false }).then(() => true, () => false);
+    await change();
+    if (!watching)
+        return;
+    await callFunction(connector, context, "() => globalThis.__resized", [], sandbox).catch(() => undefined);
+}

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

@@ -1,6 +1,6 @@
 import { type ResolvedBrowser } from "../browsers/resolve.js";
 import type { SupportedBrowser } from "../types/browser.js";
-import { type BrowserLaunchOptions } from "./browser.js";
+import type { BrowserLaunchOptions } from "./launch-flags.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";
 /**

package/dist/browser/warm-up.js

@@ -2,7 +2,8 @@ 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";
+import { Browser } from "./browser.js";
+import { BrowserStartTimeoutError } from "./session.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";
 /**

package/dist/browsers/index.d.ts

@@ -1,6 +1,6 @@
 export { browsersCacheDir } from "./cache-dir.js";
 export type { CachedBuild, Downloader } from "./downloader.js";
 export { ENV_CHROMEDRIVER_PATH, ENV_PATH, type Override } from "./overrides.js";
-export { LAUNCHABLE, MANAGED_BROWSERS, PINNED, isManagedBrowser, type ManagedBrowser, } from "./pins.js";
+export { 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, managedChromedriver, managedExecutable, uninstallBrowser, type BrowserStatus, type InstalledBuild, type StoreOptions, } from "./store.js";

package/dist/browsers/index.js

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

package/dist/browsers/pins.d.ts

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

package/dist/browsers/pins.js

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

package/dist/browsers/store.d.ts

@@ -20,8 +20,6 @@ export interface BrowserStatus {
     /** 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;
 }

package/dist/browsers/store.js

@@ -3,7 +3,7 @@ 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";
+import { isManagedBrowser, 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-";
@@ -107,7 +107,6 @@ export function statusOf(name, options = {}) {
         name,
         label: pin.label,
         buildId: pin.buildId,
-        launchable: LAUNCHABLE.includes(name),
         ...(override && { override }),
     };
     if (!downloader.platform())

package/dist/cli/args.d.ts

@@ -1,8 +1,8 @@
 import { type ProjectOptions, type RunnerOptions } from "../runner/run.js";
 /** `firefox` or `chrome` */
 type SupportedBrowser = NonNullable<RunnerOptions["browsers"]>[number];
-/** The values a command line can override for one run */
-type RunOverrides = Pick<ProjectOptions, "environment" | "timeout" | "expectTimeout">;
+/** The values a command line can override for one run: the environment and the two timeouts */
+type EnvAndTimeouts = Pick<ProjectOptions, "environment" | "timeout" | "expectTimeout">;
 /** Flags and positional arguments of a command line; an unknown flag is an error */
 export declare function parseCommandLine(argv: string[]): {
     values: {
@@ -11,6 +11,7 @@ export declare function parseCommandLine(argv: string[]): {
         "expect-timeout"?: string | undefined;
         headless?: boolean | undefined;
         port?: string | undefined;
+        workers?: string | undefined;
         grep?: string | undefined;
         group?: string | undefined;
         browser?: string[] | undefined;
@@ -29,18 +30,24 @@ export declare function parseCommandLine(argv: string[]): {
     };
     positionals: string[];
 };
+/** What `parseCommandLine` returns */
+export type ParsedCommandLine = ReturnType<typeof parseCommandLine>;
+/** The flag values of a command line, parsed once by the caller or here from `argv` */
+export type CommandValues = ParsedCommandLine["values"];
 /** How the command line says tests are selected and the browser starts */
 export interface RunnerFlags {
     headless?: boolean;
     port?: number;
+    /** `--workers`: a whole number or a percentage like `50%`, as typed */
+    workers?: string;
     grep?: string;
     group?: string;
     files?: string[];
     /** `--browser`, repeated for more than one; replaces the config's `browsers` for this run */
     browsers?: SupportedBrowser[];
 }
-/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv` */
-export declare function parseRunnerFlags(argv: string[]): RunnerFlags;
-/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
-export declare function parseRunOverrides(argv: string[], env?: Partial<NodeJS.ProcessEnv>): RunOverrides;
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+export declare function parseRunnerFlags(source: string[] | CommandValues): RunnerFlags;
+/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv` (or values parsed already); the environment falls back to SAMURAI_ENV */
+export declare function parseRunOverrides(source: string[] | CommandValues, env?: Partial<NodeJS.ProcessEnv>): EnvAndTimeouts;
 export {};

package/dist/cli/args.js

@@ -1,11 +1,12 @@
 import { parseArgs } from "node:util";
-import { checkBrowserList, } from "../runner/run.js";
+import { checkBrowserList, parseWorkers, } from "../runner/run.js";
 const FLAGS = {
     env: { type: "string" },
     timeout: { type: "string" },
     "expect-timeout": { type: "string" },
     headless: { type: "boolean" },
     port: { type: "string" },
+    workers: { type: "string" },
     grep: { type: "string" },
     group: { type: "string" },
     browser: { type: "string", multiple: true },
@@ -32,12 +33,10 @@ export function parseCommandLine(argv) {
         allowPositionals: true,
     });
 }
-function parseFlags(argv) {
-    return parseCommandLine(argv).values;
-}
-/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv` */
-export function parseRunnerFlags(argv) {
-    const values = parseFlags(argv);
+const valuesOf = (source) => Array.isArray(source) ? parseCommandLine(source).values : source;
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+export function parseRunnerFlags(source) {
+    const values = valuesOf(source);
     const flags = {};
     if (values.headless !== undefined)
         flags.headless = values.headless;
@@ -48,6 +47,10 @@ export function parseRunnerFlags(argv) {
         }
         flags.port = port;
     }
+    if (values.workers !== undefined) {
+        parseWorkers(values.workers, "--workers");
+        flags.workers = values.workers;
+    }
     if (values.grep !== undefined)
         flags.grep = values.grep;
     if (values.group !== undefined)
@@ -60,9 +63,9 @@ export function parseRunnerFlags(argv) {
     }
     return flags;
 }
-/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv`; the environment falls back to SAMURAI_ENV */
-export function parseRunOverrides(argv, env = {}) {
-    const values = parseFlags(argv);
+/** Reads `--env`, `--timeout` and `--expect-timeout` from `argv` (or values parsed already); the environment falls back to SAMURAI_ENV */
+export function parseRunOverrides(source, env = {}) {
+    const values = valuesOf(source);
     const overrides = {};
     const environment = values.env ?? env.SAMURAI_ENV;
     if (environment)

package/dist/cli/browsers.d.ts

@@ -1,6 +1,5 @@
 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";
+import type { Io } from "./io.js";
 export declare function formatBytes(n: number): string;
 /** `samurai browsers …`; `options` is for tests. The cache folder follows `io.env` */
 export declare function browsersCommand(argv: string[], io: Io, options?: StoreOptions): Promise<number>;

package/dist/cli/browsers.js

@@ -1,6 +1,6 @@
 import { browsersCacheDir, browserStatus, installBrowser, isManagedBrowser, listInstalled, MANAGED_BROWSERS, PINNED, uninstallBrowser, } from "../browsers/index.js";
 import { parseCommandLine } from "./args.js";
-export const BROWSERS_USAGE = `Usage:
+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>]
@@ -96,7 +96,7 @@ export async function browsersCommand(argv, io, options = {}) {
                 return 0;
             }
             if (target === undefined || target === "all") {
-                io.err(`Which browser? \n\n${BROWSERS_USAGE}`);
+                io.err(`Which browser?\n\n${BROWSERS_USAGE}`);
                 return 2;
             }
             const [name] = names(target);

package/dist/cli/console-reporter.js

@@ -1,3 +1,4 @@
+import { painter } from "./paint.js";
 const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
 /** Prints a run for a person: one line per test as it ends, then every failure in full and a count */
 export class ConsoleReporter {
@@ -5,13 +6,13 @@ export class ConsoleReporter {
         /** Whether the run has more than one browser: only then is each test labelled with its browser */
         this.labelled = false;
         this.write = write;
-        this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
+        this.paint = painter(color);
     }
     handle(event) {
         switch (event.type) {
             case "run-start":
                 this.labelled = event.browsers.length > 1;
-                this.write(`Running ${event.total} ${event.total === 1 ? "test" : "tests"} against ${event.environment}${this.labelled ? ` in ${event.browsers.join(", ")}` : ""}\n`);
+                this.write(`Running ${event.total} ${event.total === 1 ? "test" : "tests"}${event.workers ? ` with ${event.workers} workers` : ""} against ${event.environment}${this.labelled ? ` in ${event.browsers.join(", ")}` : ""}\n`);
                 return;
             case "test-end":
                 this.write(`  ${this.line(event.name, event.result, event.browser)}\n`);

package/dist/cli/flow-reporter.js

@@ -1,6 +1,7 @@
 import { nodeDef, } from "../flows/core/index.js";
 import { maskSecrets as maskText, } from "../flows/run/index.js";
 import { STEP_NODES } from "../flows/steps/index.js";
+import { painter } from "./paint.js";
 const took = (ms) => ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 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. */
@@ -10,7 +11,7 @@ export class FlowReporter {
         this.steps = steps ?? STEP_NODES;
         this.flow = flow;
         this.write = write;
-        this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
+        this.paint = painter(color);
         this.nodes = new Map(flow.nodes.map((n) => [n.id, n]));
     }
     shapeOf(node) {

package/dist/cli/flow.d.ts

@@ -1,4 +1,3 @@
-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 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";
+import type { Io } from "./io.js";
 /** `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,10 +1,12 @@
 import path from "node:path";
 import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
 import { FlowReporter } from "./flow-reporter.js";
+import { painter } from "./paint.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:
+import { DEFAULT_PORT } from "../runner/run.js";
+const FLOW_USAGE = `Usage:
   samurai flow list [--json]                    List the flows in ./flows
   samurai flow check [<flow>...] [options]      Check flows without running them (all flows when none is given)
   samurai flow run <flow>... [options]          Run flows, in the order given
@@ -21,7 +23,8 @@ Options for run:
   --timeout <ms>              Time one test may take
   --expect-timeout <ms>       Time actions and assertions retry
   --headless, --no-headless   Run the browser without a window, or with one
-  --port <n>                  Browser debugging port (default 9223)
+  --port <n>                  Browser debugging port (default ${DEFAULT_PORT})
+  --workers <n|n%>            Worker processes the tests share (or SAMURAI_WORKERS; default half the CPUs)
 
 Each run writes result/flows/<id>.json.
 Exit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,
@@ -38,11 +41,8 @@ const describe = (flow, p) => {
         ...(node?.title && { title: node.title }),
     };
 };
-function paintWith(io) {
-    return (code, text) => io.color ? `\u001b[${code}m${text}\u001b[0m` : text;
-}
 function problemLines(io, problems) {
-    const paint = paintWith(io);
+    const paint = painter(io.color);
     return problems
         .map((p) => {
         const who = p.key
@@ -89,6 +89,15 @@ async function list(io, json) {
                 : `${row.id}  ${row.name}  (${row.nodes} ${row.nodes === 1 ? "node" : "nodes"})\n`);
     return 0;
 }
+/** Checks one flow of the project, the same way for `check` and for the refusal before a run */
+function checkOne(projectDir, flow, options) {
+    return checkFlowInProject({
+        projectDir,
+        flow,
+        unsupported: options.unsupported,
+        ...(options.environment && { environment: options.environment }),
+    });
+}
 async function check(refs, io, options) {
     const projectDir = process.cwd();
     const targets = refs.length ? refs : await everyFlow(projectDir);
@@ -104,12 +113,7 @@ async function check(refs, io, options) {
             code = 2;
             continue;
         }
-        const result = await checkFlowInProject({
-            projectDir,
-            flow,
-            unsupported: options.unsupported,
-            ...(options.environment && { environment: options.environment }),
-        });
+        const result = await checkOne(projectDir, flow, options);
         const problems = result.problems.map((p) => describe(result.flow, p));
         all.push(...problems);
         if (code === 0 && problems.some((p) => p.level === "error"))
@@ -141,19 +145,14 @@ async function run(refs, io, options) {
     // Several flows: refuse them all before the first one runs
     if (flows.length > 1) {
         for (const flow of flows) {
-            const { problems } = await checkFlowInProject({
-                projectDir,
-                flow,
-                unsupported: options.unsupported,
-                ...(options.environment && { environment: options.environment }),
-            });
+            const { problems } = await checkOne(projectDir, flow, options);
             const errors = problems.filter((p) => p.level === "error");
             if (errors.length)
                 return refuse(errors, flow);
         }
     }
     let code = 0;
-    for (const flow of flows) {
+    for (const [index, flow] of flows.entries()) {
         if (io.signal?.aborted) {
             code = 1;
             break;
@@ -162,7 +161,7 @@ async function run(refs, io, options) {
         const human = options.json
             ? undefined
             : new FlowReporter({ flow, write: io.out, color: io.color, steps });
-        if (flows.indexOf(flow) > 0 && !options.json)
+        if (index > 0 && !options.json)
             io.out("\n");
         let summary;
         try {
@@ -200,7 +199,7 @@ export async function flowCommand(argv, io) {
     const [sub, ...refs] = positionals;
     const unsupported = values["allow-unsupported"] ? "skip" : "fail";
     const json = values.json === true;
-    const overrides = parseRunOverrides(argv, io.env);
+    const overrides = parseRunOverrides(values, io.env);
     try {
         if (sub === "list" && refs.length === 0)
             return await list(io, json);
@@ -215,7 +214,7 @@ export async function flowCommand(argv, io) {
                 throw new UsageError("Give flows or --all, not both.");
             if (!values.all && refs.length === 0)
                 throw new UsageError("Which flow? Give a flow or --all.");
-            const flags = parseRunnerFlags(argv);
+            const flags = parseRunnerFlags(values);
             const targets = values.all ? await everyFlow(process.cwd()) : refs;
             return await run(targets, io, {
                 json,
@@ -225,6 +224,10 @@ export async function flowCommand(argv, io) {
                     ...overrides,
                     ...(flags.headless !== undefined && { headless: flags.headless }),
                     ...(flags.port !== undefined && { port: flags.port }),
+                    ...(flags.workers !== undefined && { workers: flags.workers }),
+                    ...(io.env.SAMURAI_WORKERS && {
+                        workersEnv: io.env.SAMURAI_WORKERS,
+                    }),
                 },
             });
         }

package/dist/cli/init.js

@@ -1,12 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { frameworkVersion } from "./version.js";
 const PACKAGE = "@itmetsam/samurai-framework";
-/** The version of this package, so a new project asks for the release that scaffolded it */
-function frameworkVersion() {
-    const manifest = new URL("../../package.json", import.meta.url);
-    return JSON.parse(readFileSync(manifest, "utf8"))
-        .version;
-}
 /** The files `samurai init` writes, by path relative to the project folder */
 export function scaffold(name) {
     return {

package/dist/cli/io.d.ts

@@ -0,0 +1,10 @@
+/** What the command line reads from and writes to; the process supplies it, tests fake it */
+export interface Io {
+    out: (text: string) => void;
+    err: (text: string) => void;
+    /** Whether output goes to a terminal that shows colours */
+    color: boolean;
+    env: Partial<NodeJS.ProcessEnv>;
+    /** Aborts a recording (Ctrl+C) */
+    signal?: AbortSignal;
+}

package/dist/cli/io.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/main.d.ts

@@ -1,12 +1,5 @@
-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  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\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, --headless, --no-headless):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\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;
-    /** Whether output goes to a terminal that shows colours */
-    color: boolean;
-    env: Partial<NodeJS.ProcessEnv>;
-    /** Aborts a recording (Ctrl+C) */
-    signal?: AbortSignal;
-}
+import type { Io } from "./io.js";
+import { USAGE } from "./usage.js";
+export { USAGE };
 /** The command line as `samurai` runs it. Returns the exit code */
 export declare function main(argv: string[], io: Io): Promise<number>;