@itmetsam/samurai-framework 0.9.0 → 0.12.0

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

package/dist/cli/main.js

@@ -1,68 +1,13 @@
-import { readFileSync } from "node:fs";
 import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
-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
-
-Usage:
-  samurai run [options]       Run the tests (the default command)
-  samurai list [options]      List the tests without running them
-  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)
-  --file <spec>               Only this spec file; repeatable
-  --grep <text>               Only tests whose full name contains the text
-  --group <name>              Only the tests of this group of the config's groups
-  --json                      Machine-readable output: JSON lines for run, one array for list
-
-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.
-                              Default: the config's use.headless, else headless when CI is set
-  --port <n>                  Browser debugging port (default 9223)
-
-Options for record (also --env, --port, --json, --headless, --no-headless):
-  --new <title>               Add a test with this title (creates the spec file if needed)
-  --test <name|index>         Record into this test; not needed when the file has one
-  --at <n>                    Insert from step n (default: after the last step)
-  --url <url>                 Page to start on (default: the environment's baseURL)
-  Stop with Ctrl+C or by closing the browser window.
-
-  -h, --help                  Show this help
-  -v, --version               Show the version
-
-Exit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.
-
-samurai flow:
-  list                        The flows in ./flows
-  check [<flow>...]           Check flows without running them
-  run <flow>... | --all       Run flows; each writes result/flows/<id>.json
-  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() {
-    const manifest = new URL("../../package.json", import.meta.url);
-    return JSON.parse(readFileSync(manifest, "utf8"))
-        .version;
-}
+import { recordCommand } from "./record.js";
+import { USAGE } from "./usage.js";
+import { frameworkVersion } from "./version.js";
+export { USAGE };
 /** The command line as `samurai` runs it. Returns the exit code */
 export async function main(argv, io) {
     try {
@@ -75,7 +20,7 @@ export async function main(argv, io) {
             return 0;
         }
         if (values.version) {
-            io.out(`${version()}\n`);
+            io.out(`${frameworkVersion()}\n`);
             return 0;
         }
         if (command === "flow")
@@ -91,93 +36,22 @@ export async function main(argv, io) {
             io.out("\nNext: install the dependencies, then `samurai browsers install firefox`, then `samurai run`.\n");
             return 0;
         }
-        if (command === "record") {
-            const file = positionals[0];
-            if (!file)
-                throw new Error("Which spec? Usage: samurai record <spec> [--new <title>]");
-            const at = values.at === undefined ? undefined : Number(values.at);
-            if (at !== undefined && (!Number.isInteger(at) || at < 0))
-                throw new Error(`--at must be a step number, got "${values.at}"`);
-            const flags = parseRunnerFlags(rest);
-            const test = values.test === undefined
-                ? undefined
-                : /^\d+$/.test(values.test)
-                    ? Number(values.test)
-                    : values.test;
-            let count = 0;
-            let state = "recording";
-            let toolbarWarned = false;
-            const result = await recordSpec({
-                ...parseRunOverrides(rest, io.env),
-                file,
-                ...(test !== undefined && { test }),
-                ...(values.new !== undefined && { create: values.new }),
-                ...(at !== undefined && { at }),
-                ...(values.url !== undefined && { url: values.url }),
-                ...(flags.headless !== undefined && { headless: flags.headless }),
-                ...(flags.port !== undefined && { port: flags.port }),
-                ...(io.signal && { signal: io.signal }),
-                onStarted: () => {
-                    if (!values.json)
-                        io.out("Recording. Alt+click an element to assert on it. Press Stop in the toolbar, Ctrl+C or close the window to stop.\n");
-                },
-                onStatus: (status) => {
-                    if (values.json)
-                        return;
-                    if (!status.toolbar && !toolbarWarned) {
-                        toolbarWarned = true;
-                        io.out("The toolbar couldn't load on this page. Alt+click still records assertions.\n");
-                    }
-                    if (status.state !== state) {
-                        state = status.state;
-                        io.out(state === "paused" ? "Paused\n" : "Recording\n");
-                    }
-                },
-                onMissingFile: (_file, text) => {
-                    if (!values.json)
-                        io.out(`${text}\n`);
-                },
-                onEvent: (event) => {
-                    if (values.json)
-                        return void io.out(`${JSON.stringify(event)}\n`);
-                    if (event.op === "remove") {
-                        count--;
-                        return void io.out(`  - step ${event.index + 1} (the click that opened the file picker)\n`);
-                    }
-                    io.out(`  ${event.op === "insert" ? "+" : "~"} ${stepToSource(event.step)}\n`);
-                    if (event.op === "insert")
-                        count++;
-                },
-            });
-            if (!values.json) {
-                io.out(`\nRecorded ${count} ${count === 1 ? "step" : "steps"} into "${result.test}" in ${result.file}\n`);
-                if (result.unsetSecrets.length > 0) {
-                    io.out(`Set ${result.unsetSecrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
-                }
-                if (result.missingFiles.length > 0) {
-                    io.out(`Add ${result.missingFiles.map((f) => f.path).join(", ")} before running it (or use generatedFile).\n`);
-                }
-                const hasFiles = result.files.length + result.missingFiles.length > 0;
-                const folder = result.filesFolder === "" ? "." : result.filesFolder;
-                if (hasFiles && result.filesIgnored)
-                    io.out(`${folder}/ is ignored by git; CI won't have these files.\n`);
-                if (hasFiles && result.firstFiles)
-                    io.out(`Recorded files are stored in ${folder}/ and committed with your tests.\n`);
-            }
-            return 0;
-        }
+        if (command === "record")
+            return await recordCommand({ values, positionals }, io);
         if (command !== "run" && command !== "list") {
             io.err(`Unknown command "${command}"\n\n${USAGE}`);
             return 2;
         }
-        const flags = parseRunnerFlags(rest);
+        const flags = parseRunnerFlags(values);
         const options = {
-            ...parseRunOverrides(rest, io.env),
+            ...parseRunOverrides(values, io.env),
             ...(flags.headless !== undefined && { headless: flags.headless }),
             ...(flags.port !== undefined && { port: flags.port }),
+            ...(flags.workers !== undefined && { workers: flags.workers }),
             ...(flags.grep !== undefined && { grep: flags.grep }),
             ...(flags.group !== undefined && { group: flags.group }),
             ...(flags.files && { files: flags.files }),
+            ...(flags.browsers && { browsers: flags.browsers }),
         };
         if (command === "list") {
             const tests = await listTests(options);

package/dist/cli/paint.d.ts

@@ -0,0 +1,2 @@
+/** Wraps text in an ANSI colour code when `color` is on, and leaves it as it is when not */
+export declare function painter(color: boolean): (code: number, text: string) => string;

package/dist/cli/paint.js

@@ -0,0 +1,4 @@
+/** Wraps text in an ANSI colour code when `color` is on, and leaves it as it is when not */
+export function painter(color) {
+    return (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : text);
+}

package/dist/cli/record.d.ts

@@ -0,0 +1,4 @@
+import { type ParsedCommandLine } from "./args.js";
+import type { Io } from "./io.js";
+/** `samurai record <spec>`: records into a spec file and prints what happened. Returns the exit code */
+export declare function recordCommand({ values, positionals }: ParsedCommandLine, io: Io): Promise<number>;

package/dist/cli/record.js

@@ -0,0 +1,93 @@
+import { recordSpec } from "../recorder/index.js";
+import { stepToSource } from "../steps/index.js";
+import { parseRunnerFlags, parseRunOverrides, } from "./args.js";
+/** Prints a recording for a person, or as JSON lines, while it happens; counts the steps written */
+function recordingPrinter(io, json) {
+    let count = 0;
+    let state = "recording";
+    let toolbarWarned = false;
+    const handlers = {
+        onStarted: () => {
+            if (!json)
+                io.out("Recording. Alt+click an element to assert on it. Press Stop in the toolbar, Ctrl+C or close the window to stop.\n");
+        },
+        onStatus: (status) => {
+            if (json)
+                return;
+            if (!status.toolbar && !toolbarWarned) {
+                toolbarWarned = true;
+                io.out("The toolbar couldn't load on this page. Alt+click still records assertions.\n");
+            }
+            if (status.state !== state) {
+                state = status.state;
+                io.out(state === "paused" ? "Paused\n" : "Recording\n");
+            }
+        },
+        onMissingFile: (_file, text) => {
+            if (!json)
+                io.out(`${text}\n`);
+        },
+        onEvent: (event) => {
+            if (json)
+                return void io.out(`${JSON.stringify(event)}\n`);
+            if (event.op === "remove") {
+                count--;
+                return void io.out(`  - step ${event.index + 1} (the click that opened the file picker)\n`);
+            }
+            io.out(`  ${event.op === "insert" ? "+" : "~"} ${stepToSource(event.step)}\n`);
+            if (event.op === "insert")
+                count++;
+        },
+    };
+    return { handlers, steps: () => count };
+}
+/** What is left to do after a recording: the steps written, secrets to set, files to add, notes on the files folder */
+function summarise(io, result, steps) {
+    io.out(`\nRecorded ${steps} ${steps === 1 ? "step" : "steps"} into "${result.test}" in ${result.file}\n`);
+    if (result.unsetSecrets.length > 0) {
+        io.out(`Set ${result.unsetSecrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
+    }
+    if (result.missingFiles.length > 0) {
+        io.out(`Add ${result.missingFiles.map((f) => f.path).join(", ")} before running it (or use generatedFile).\n`);
+    }
+    const hasFiles = result.files.length + result.missingFiles.length > 0;
+    const folder = result.filesFolder === "" ? "." : result.filesFolder;
+    if (hasFiles && result.filesIgnored)
+        io.out(`${folder}/ is ignored by git; CI won't have these files.\n`);
+    if (hasFiles && result.firstFiles)
+        io.out(`Recorded files are stored in ${folder}/ and committed with your tests.\n`);
+}
+/** `samurai record <spec>`: records into a spec file and prints what happened. Returns the exit code */
+export async function recordCommand({ values, positionals }, io) {
+    const file = positionals[0];
+    if (!file)
+        throw new Error("Which spec? Usage: samurai record <spec> [--new <title>]");
+    const at = values.at === undefined ? undefined : Number(values.at);
+    if (at !== undefined && (!Number.isInteger(at) || at < 0))
+        throw new Error(`--at must be a step number, got "${values.at}"`);
+    const flags = parseRunnerFlags(values);
+    if (flags.browsers && flags.browsers.length > 1)
+        throw new Error("--browser: a recording uses one browser");
+    const test = values.test === undefined
+        ? undefined
+        : /^\d+$/.test(values.test)
+            ? Number(values.test)
+            : values.test;
+    const printer = recordingPrinter(io, values.json === true);
+    const result = await recordSpec({
+        ...parseRunOverrides(values, io.env),
+        file,
+        ...(test !== undefined && { test }),
+        ...(values.new !== undefined && { create: values.new }),
+        ...(at !== undefined && { at }),
+        ...(values.url !== undefined && { url: values.url }),
+        ...(flags.headless !== undefined && { headless: flags.headless }),
+        ...(flags.port !== undefined && { port: flags.port }),
+        ...(flags.browsers && { browser: flags.browsers[0] }),
+        ...(io.signal && { signal: io.signal }),
+        ...printer.handlers,
+    });
+    if (!values.json)
+        summarise(io, result, printer.steps());
+    return 0;
+}

package/dist/cli/usage.d.ts

@@ -0,0 +1 @@
+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  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\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";

package/dist/cli/usage.js

@@ -0,0 +1,58 @@
+import { DEFAULT_PORT } from "../runner/run.js";
+export const USAGE = `samurai: browser tests over WebDriver BiDi
+
+Usage:
+  samurai run [options]       Run the tests (the default command)
+  samurai list [options]      List the tests without running them
+  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)
+  --file <spec>               Only this spec file; repeatable
+  --grep <text>               Only tests whose full name contains the text
+  --group <name>              Only the tests of this group of the config's groups
+  --browser <name>            Run in this browser (firefox or chrome) instead of the config's
+                              browsers; repeat it for more than one
+  --json                      Machine-readable output: JSON lines for run, one array for list
+
+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.
+                              Default: the config's use.headless, else headless when CI is set
+  --port <n>                  Browser debugging port (default ${DEFAULT_PORT})
+  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number
+                              from 1, or a share of the CPUs like 50%. Default: the config's
+                              workers (or SAMURAI_WORKERS), else half the CPUs
+
+Options for record (also --env, --port, --json, --headless, --no-headless):
+  --browser <name>            Record in this browser (default: the first of the config's browsers)
+  --new <title>               Add a test with this title (creates the spec file if needed)
+  --test <name|index>         Record into this test; not needed when the file has one
+  --at <n>                    Insert from step n (default: after the last step)
+  --url <url>                 Page to start on (default: the environment's baseURL)
+  Stop with Ctrl+C or by closing the browser window.
+
+  -h, --help                  Show this help
+  -v, --version               Show the version
+
+Exit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.
+
+samurai flow:
+  list                        The flows in ./flows
+  check [<flow>...]           Check flows without running them
+  run <flow>... | --all       Run flows; each writes result/flows/<id>.json
+  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.
+`;

package/dist/cli/version.d.ts

@@ -0,0 +1,2 @@
+/** The version of this package */
+export declare function frameworkVersion(): string;

package/dist/cli/version.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+/** The version of this package */
+export function frameworkVersion() {
+    const manifest = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(manifest, "utf8"))
+        .version;
+}

package/dist/config/browsers.d.ts

@@ -0,0 +1,11 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Every browser a config may name, in the order the messages list them */
+export declare const BROWSER_NAMES: readonly SupportedBrowser[];
+/** Throws when `list` is not a non-empty list of distinct browser names; `where` names the key in the message */
+export declare function checkBrowserList(list: unknown, where: string): void;
+/**
+ * Checks the browser keys of a config: the removed `browser`, and `browsers` on the project and on each group.
+ * Throws an Error that says what to write instead.
+ */
+export declare function validateBrowserConfig(config: SamuraiTestConfig): void;

package/dist/config/browsers.js

@@ -0,0 +1,32 @@
+/** Every browser a config may name, in the order the messages list them */
+export const BROWSER_NAMES = ["firefox", "chrome"];
+const isBrowser = (value) => typeof value === "string" &&
+    BROWSER_NAMES.includes(value);
+/** Throws when `list` is not a non-empty list of distinct browser names; `where` names the key in the message */
+export function checkBrowserList(list, where) {
+    if (!Array.isArray(list) || list.length === 0)
+        throw new Error(`${where} must list at least one browser.`);
+    const seen = new Set();
+    for (const name of list) {
+        if (!isBrowser(name))
+            throw new Error(`Unknown browser "${String(name)}" in ${where}. Choose ${BROWSER_NAMES.join(" or ")}.`);
+        if (seen.has(name))
+            throw new Error(`Browser "${name}" is listed twice in ${where}.`);
+        seen.add(name);
+    }
+}
+/**
+ * Checks the browser keys of a config: the removed `browser`, and `browsers` on the project and on each group.
+ * Throws an Error that says what to write instead.
+ */
+export function validateBrowserConfig(config) {
+    const legacy = config.browser;
+    if (legacy !== undefined)
+        throw new Error(`"browser" was replaced by "browsers": use browsers: [${JSON.stringify(legacy)}]`);
+    if (config.browsers !== undefined)
+        checkBrowserList(config.browsers, "browsers");
+    config.groups?.forEach((group, index) => {
+        if (group.browsers !== undefined)
+            checkBrowserList(group.browsers, `groups[${index}].browsers`);
+    });
+}

package/dist/config/config.js

@@ -1,6 +1,8 @@
 import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
+import { validateBrowserConfig } from "./browsers.js";
+import { validateWorkersConfig } from "./workers.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
 export function setActiveProject(project) {
@@ -22,14 +24,19 @@ export function browsersDir() {
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadConfig() {
-    if (activeProject?.config)
+    if (activeProject?.config) {
+        validateBrowserConfig(activeProject.config);
+        validateWorkersConfig(activeProject.config);
         return activeProject.config;
+    }
     const configUrl = path.join(projectDir(), "samurai.config.ts");
     logger.debug("Reading config from: %s", configUrl);
     const config = (await import(pathToFileURL(configUrl).href));
     if (!config.default) {
         throw new Error("samurai.config.ts does not export defineConfig as default!");
     }
+    validateBrowserConfig(config.default);
+    validateWorkersConfig(config.default);
     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 */

package/dist/config/mask.d.ts

@@ -1,7 +1,7 @@
 export declare const MASK = "\u2022\u2022\u2022\u2022";
 /** Registers a secret value; every later maskText/maskDeep/log line hides it */
 export declare function registerSecret(name: string, value: string): void;
-/** Forgets every registered secret (tests only) */
+/** Forgets every registered secret: a run starts with none */
 export declare function resetSecrets(): void;
 export declare function isShortSecret(value: string): boolean;
 export declare function maskText(text: string): string;

package/dist/config/mask.js

@@ -12,7 +12,7 @@ export function registerSecret(name, value) {
     secrets.set(name, value);
     rebuild();
 }
-/** Forgets every registered secret (tests only) */
+/** Forgets every registered secret: a run starts with none */
 export function resetSecrets() {
     secrets.clear();
     patterns = [];
@@ -25,7 +25,12 @@ function escapeRegExp(value) {
 }
 /** A value plus its JSON-escaped, inspect-escaped and percent-encoded spellings */
 function variants(value) {
-    const forms = [value, JSON.stringify(value).slice(1, -1), inspect(value).slice(1, -1), encodeURIComponent(value)];
+    const forms = [
+        value,
+        JSON.stringify(value).slice(1, -1),
+        inspect(value).slice(1, -1),
+        encodeURIComponent(value),
+    ];
     return forms.filter((form) => form !== "");
 }
 function rebuild() {

package/dist/config/run-settings.d.ts

@@ -23,9 +23,9 @@ export interface RunSettings {
 export declare class UnknownEnvironmentError extends Error {
     constructor(message: string);
 }
-/** Picks the environment and applies precedence: run override > environment > project > built-in default */
 /** True when the `CI` environment variable says this is a CI run (set, and not "", "0" or "false") */
 export declare function isCI(env?: Partial<NodeJS.ProcessEnv>): boolean;
+/** Picks the environment and applies precedence: run override > environment > project > built-in default */
 export declare function resolveRunSettings(config: SamuraiTestConfig, overrides?: RunOverrides, 
 /** Where `CI` is read from */
 env?: Partial<NodeJS.ProcessEnv>): RunSettings;
@@ -33,4 +33,3 @@ env?: Partial<NodeJS.ProcessEnv>): RunSettings;
 export declare function setRunSettings(settings: RunSettings | undefined): void;
 /** The active run's settings, or undefined outside a run (unit and browser tests) */
 export declare function peekRunSettings(): RunSettings | undefined;
-export declare function getRunSettings(): RunSettings;

package/dist/config/run-settings.js

@@ -8,12 +8,12 @@ export class UnknownEnvironmentError extends Error {
         this.name = "UnknownEnvironmentError";
     }
 }
-/** Picks the environment and applies precedence: run override > environment > project > built-in default */
 /** True when the `CI` environment variable says this is a CI run (set, and not "", "0" or "false") */
 export function isCI(env = process.env) {
     const value = env.CI?.trim().toLowerCase();
     return (value !== undefined && value !== "" && value !== "0" && value !== "false");
 }
+/** Picks the environment and applies precedence: run override > environment > project > built-in default */
 export function resolveRunSettings(config, overrides = {}, 
 /** Where `CI` is read from */
 env = process.env) {
@@ -65,8 +65,3 @@ export function setRunSettings(settings) {
 export function peekRunSettings() {
     return active;
 }
-export function getRunSettings() {
-    if (!active)
-        throw new Error("No test run is active; run settings are set when the runner starts");
-    return active;
-}

package/dist/config/timeouts.d.ts

@@ -0,0 +1,2 @@
+/** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
+export declare function resolveTimeout(perCall?: number): Promise<number>;

package/dist/config/timeouts.js

@@ -0,0 +1,13 @@
+import { readConfig } from "./config.js";
+import { peekRunSettings } from "./run-settings.js";
+/** The retry time of actions and assertions when nothing sets one (ms) */
+const DEFAULT_EXPECT_TIMEOUT = 5000;
+/** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
+export async function resolveTimeout(perCall) {
+    if (perCall !== undefined)
+        return perCall;
+    const run = peekRunSettings();
+    if (run)
+        return run.expectTimeout;
+    return (await readConfig("expect"))?.timeout ?? DEFAULT_EXPECT_TIMEOUT;
+}

package/dist/config/workers.d.ts

@@ -0,0 +1,14 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** A number of workers, or a share of the CPUs */
+export type ParsedWorkers = {
+    count: number;
+} | {
+    percent: number;
+};
+/**
+ * Reads a `workers` value: a whole number from 1, as a number or as text, or a percentage like `50%` when
+ * `percentages` is on. `where` names the source (`--workers`, `SAMURAI_WORKERS`, a config key) in the error.
+ */
+export declare function parseWorkers(value: unknown, where: string, percentages?: boolean): ParsedWorkers;
+/** Checks the `workers` keys of a config: the project's and each group's. Throws an Error that names the key */
+export declare function validateWorkersConfig(config: SamuraiTestConfig): void;

package/dist/config/workers.js

@@ -0,0 +1,29 @@
+/**
+ * Reads a `workers` value: a whole number from 1, as a number or as text, or a percentage like `50%` when
+ * `percentages` is on. `where` names the source (`--workers`, `SAMURAI_WORKERS`, a config key) in the error.
+ */
+export function parseWorkers(value, where, percentages = true) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1)
+        return { count: value };
+    if (typeof value === "string") {
+        const text = value.trim();
+        if (/^\d+$/.test(text) && Number(text) >= 1)
+            return { count: Number(text) };
+        const share = /^(\d+)%$/.exec(text);
+        if (percentages && share) {
+            const percent = Number(share[1]);
+            if (percent >= 1 && percent <= 100)
+                return { percent };
+        }
+    }
+    throw new Error(`${where} must be a whole number from 1${percentages ? " or a percentage like 50%" : ""}, got "${String(value)}"`);
+}
+/** Checks the `workers` keys of a config: the project's and each group's. Throws an Error that names the key */
+export function validateWorkersConfig(config) {
+    if (config.workers !== undefined)
+        parseWorkers(config.workers, "workers");
+    config.groups?.forEach((group, index) => {
+        if (group.workers !== undefined)
+            parseWorkers(group.workers, `groups[${index}].workers`, false);
+    });
+}

package/dist/flows/run/branch-context.d.ts

@@ -0,0 +1,14 @@
+import type { ExpressionContext } from "../core/index.js";
+/** A branch of a Parallel node: its own copy of the variables and node outputs, and the variables as they were when it forked */
+export interface Fork {
+    context: ExpressionContext;
+    base: Record<string, unknown>;
+}
+export declare function forkContext(context: ExpressionContext): Fork;
+/**
+ * Takes what the branches wrote into `into`: every node output, and every variable a branch changed. A variable
+ * two branches changed to different values is a clash and is not taken; the first clash is returned.
+ */
+export declare function mergeForks(into: ExpressionContext, forks: readonly Fork[]): {
+    clash?: string;
+};