@itmetsam/samurai-framework 0.2.3 → 0.4.0

package/README.md

@@ -92,6 +92,10 @@ A browser window opens for each test and closes when the test ends. The result i
 
 > `src/tests/index.spec.ts` is an example that submits a real contact form. Delete it or replace it before running everything.
 
+### Flows (optional)
+
+A project can also keep flows in `flows/*.flow.json` (edited in the Samurai app) that chain tests and groups with conditions and variables. `samurai flow check` validates them and `samurai flow run <flow>` runs them, with a report in `result/flows/`. See [Flows](docs/flows.md).
+
 ### 6. Secrets (optional)
 
 ```sh
@@ -113,6 +117,7 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Configuration](docs/configuration.md)                       | Every option in `samurai.config.ts`, CLI flags and precedence                                         |
 | [Environments and secrets](docs/environments-and-secrets.md) | Per-environment settings, variables, secrets and masking                                              |
 | [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
+| [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
 | [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
 | [Steps and the recorder](docs/recorder.md)                   | The step codec and the recording engine                                                               |
 | [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |

package/bin/samurai.mjs

@@ -15,12 +15,14 @@ try {
 }
 
 const { main } = await import("../dist/cli/main.js");
-// Ctrl+C ends a recording cleanly (the browser is closed, the file is complete); a second one stops at once
+// Ctrl+C (or a termination signal) ends a recording or a flow run cleanly (the browser is closed, the file is complete); a second one stops at once
 const interrupt = new AbortController();
-process.on("SIGINT", () => {
-  if (interrupt.signal.aborted) process.exit(130);
-  interrupt.abort();
-});
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    if (interrupt.signal.aborted) process.exit(130);
+    interrupt.abort();
+  });
+}
 const code = await main(process.argv.slice(2), {
   out: (text) => process.stdout.write(text),
   err: (text) => process.stderr.write(text),

package/dist/cli/args.d.ts

@@ -10,8 +10,11 @@ export declare function parseCommandLine(argv: string[]): {
         headless?: boolean | undefined;
         port?: string | undefined;
         grep?: string | undefined;
+        group?: string | undefined;
         file?: string[] | undefined;
         json?: boolean | undefined;
+        all?: boolean | undefined;
+        "allow-unsupported"?: boolean | undefined;
         test?: string | undefined;
         at?: string | undefined;
         new?: string | undefined;
@@ -26,9 +29,10 @@ export interface RunnerFlags {
     headless?: boolean;
     port?: number;
     grep?: string;
+    group?: string;
     files?: string[];
 }
-/** Reads `--headless`, `--port <n>`, `--grep <text>` and `--file <spec>` (repeatable) from `argv` */
+/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>` and `--file <spec>` (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;

package/dist/cli/args.js

@@ -6,8 +6,11 @@ const FLAGS = {
     headless: { type: "boolean" },
     port: { type: "string" },
     grep: { type: "string" },
+    group: { type: "string" },
     file: { type: "string", multiple: true },
     json: { type: "boolean" },
+    all: { type: "boolean" },
+    "allow-unsupported": { type: "boolean" },
     test: { type: "string" },
     at: { type: "string" },
     new: { type: "string" },
@@ -28,7 +31,7 @@ export function parseCommandLine(argv) {
 function parseFlags(argv) {
     return parseCommandLine(argv).values;
 }
-/** Reads `--headless`, `--port <n>`, `--grep <text>` and `--file <spec>` (repeatable) from `argv` */
+/** Reads `--headless`, `--port <n>`, `--grep <text>`, `--group <name>` and `--file <spec>` (repeatable) from `argv` */
 export function parseRunnerFlags(argv) {
     const values = parseFlags(argv);
     const flags = {};
@@ -43,6 +46,8 @@ export function parseRunnerFlags(argv) {
     }
     if (values.grep !== undefined)
         flags.grep = values.grep;
+    if (values.group !== undefined)
+        flags.group = values.group;
     if (values.file?.length)
         flags.files = values.file;
     return flags;

package/dist/cli/flow-reporter.d.ts

@@ -0,0 +1,23 @@
+import { 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;
+}
+/** 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 {
+    private readonly write;
+    private readonly paint;
+    private readonly nodes;
+    private readonly flow;
+    private started;
+    constructor({ flow, write, color }: FlowReporterOptions);
+    private shapeOf;
+    private listed;
+    private nameOf;
+    handle(event: FlowEvent): void;
+    private line;
+    private summary;
+}

package/dist/cli/flow-reporter.js

@@ -0,0 +1,98 @@
+import { nodeDef, } from "../flows/core/index.js";
+import { maskSecrets as maskText, } from "../flows/run/index.js";
+import { STEP_NODES } from "../flows/steps/index.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. */
+export class FlowReporter {
+    constructor({ flow, write, color }) {
+        this.started = Date.now();
+        this.flow = flow;
+        this.write = write;
+        this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
+        this.nodes = new Map(flow.nodes.map((n) => [n.id, n]));
+    }
+    shapeOf(node) {
+        try {
+            return nodeDef(node.kind).shape;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    listed(node) {
+        return !!node && !SKIPPED_BY_SHAPE.has(this.shapeOf(node) ?? "");
+    }
+    nameOf(node, result) {
+        let label;
+        try {
+            label = nodeDef(node.kind).label;
+        }
+        catch {
+            label = STEP_NODES.find((d) => d.kind === node.kind)?.label ?? node.kind;
+        }
+        const base = node.title || label;
+        const wrote = result.wrote ? Object.keys(result.wrote) : [];
+        return node.title || wrote.length === 0
+            ? base
+            : `${base} ${wrote.map((n) => `vars.${n}`).join(", ")}`;
+    }
+    handle(event) {
+        if (event.type === "flow-start") {
+            this.started = Date.now();
+            this.write(`Flow "${this.flow.name}" against ${event.environment}\n`);
+        }
+        else if (event.type === "node-end") {
+            const node = this.nodes.get(event.nodeId);
+            if (this.listed(node))
+                this.line(node, event.result);
+        }
+        else if (event.type === "flow-end") {
+            this.summary(event.summary);
+        }
+    }
+    line(node, result) {
+        const name = this.nameOf(node, result);
+        const time = result.durationMs === undefined
+            ? ""
+            : ` ${this.paint(90, `(${took(result.durationMs)})`)}`;
+        if (result.status === "failed") {
+            this.write(`  ${this.paint(31, "✖")} ${name}${time}\n`);
+            if (result.error)
+                this.write(`${maskText(result.error)
+                    .split("\n")
+                    .map((l) => `      ${l}`)
+                    .join("\n")}\n`);
+        }
+        else if (result.status === "skipped") {
+            this.write(`  ${this.paint(33, "⊘")} ${name} ${this.paint(90, `(skipped${result.note ? `: ${result.note}` : ""})`)}\n`);
+        }
+        else if (result.branch !== undefined) {
+            this.write(`  ${this.paint(36, "◇")} ${name} → ${result.branch}${time}\n`);
+        }
+        else {
+            this.write(`  ${this.paint(32, "✔")} ${name}${time}\n`);
+            if (result.note)
+                this.write(`      ${this.paint(90, result.note)}\n`);
+        }
+    }
+    summary(summary) {
+        const counts = { failed: 0, passed: 0, skipped: 0, "not-run": 0 };
+        for (const [id, result] of Object.entries(summary.nodes)) {
+            if (this.listed(this.nodes.get(id)))
+                counts[result.status]++;
+        }
+        if (summary.error)
+            this.write(`\n${this.paint(31, maskText(summary.error))}\n`);
+        if (summary.status === "cancelled")
+            this.write(`\nCancelled\n`);
+        const parts = [
+            counts.failed > 0 && this.paint(31, `${counts.failed} failed`),
+            this.paint(32, `${counts.passed} passed`),
+            counts.skipped > 0 && this.paint(33, `${counts.skipped} skipped`),
+            counts["not-run"] > 0 && `${counts["not-run"]} not run`,
+        ].filter(Boolean);
+        const total = Date.now() - this.started;
+        this.write(`\n${parts.join(", ")} ${this.paint(90, `(${took(total)})`)}\n`);
+    }
+}

package/dist/cli/flow.d.ts

@@ -0,0 +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";
+/** `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

@@ -0,0 +1,240 @@
+import path from "node:path";
+import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
+import { FlowReporter } from "./flow-reporter.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:
+  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
+  samurai flow run --all [options]              Run every flow in ./flows, in file name order
+
+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
+  --json                      Machine-readable output: JSON lines for run, one array for check and 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
+  --port <n>                  Browser debugging port (default 9223)
+
+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,
+2 for a usage, configuration or flow-file error, or a flow that has errors (nothing ran).
+`;
+class UsageError extends Error {
+}
+const describe = (flow, p) => {
+    const node = p.nodeId ? flow.nodes.find((n) => n.id === p.nodeId) : undefined;
+    return {
+        ...p,
+        flow: flow.id,
+        ...(node?.key && { key: node.key }),
+        ...(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);
+    return problems
+        .map((p) => {
+        const who = p.key
+            ? `${p.key}${p.title && p.title !== p.key ? ` (${p.title})` : ""}: `
+            : "";
+        const mark = p.level === "error" ? paint(31, "✖ error  ") : paint(33, "! warning");
+        return `  ${mark} ${who}${p.message}\n`;
+    })
+        .join("");
+}
+/** A flow is an id in ./flows, or a path to a .flow.json file */
+async function load(projectDir, ref) {
+    const isPath = /[\\/]/.test(ref) || ref.endsWith(".json");
+    return isPath
+        ? readFlowPath(path.resolve(projectDir, ref))
+        : readFlow(projectDir, ref);
+}
+async function everyFlow(projectDir) {
+    const ids = await listFlows(projectDir);
+    if (ids.length === 0)
+        throw new Error(`No flows: ${flowsDir(projectDir)} has no *${FLOW_SUFFIX} files.`);
+    return ids;
+}
+async function list(io, json) {
+    const projectDir = process.cwd();
+    const rows = [];
+    for (const id of await listFlows(projectDir)) {
+        try {
+            const flow = await readFlow(projectDir, id);
+            rows.push({ id, name: flow.name, nodes: flow.nodes.length });
+        }
+        catch (e) {
+            rows.push({ id, error: e.message });
+        }
+    }
+    if (json)
+        io.out(`${JSON.stringify(rows, null, 2)}\n`);
+    else if (rows.length === 0)
+        io.out("No flows in ./flows\n");
+    else
+        for (const row of rows)
+            io.out(row.error
+                ? `${row.id}  (unreadable: ${row.error})\n`
+                : `${row.id}  ${row.name}  (${row.nodes} ${row.nodes === 1 ? "node" : "nodes"})\n`);
+    return 0;
+}
+async function check(refs, io, options) {
+    const projectDir = process.cwd();
+    const targets = refs.length ? refs : await everyFlow(projectDir);
+    const all = [];
+    let code = 0;
+    for (const ref of targets) {
+        let flow;
+        try {
+            flow = await load(projectDir, ref);
+        }
+        catch (e) {
+            io.err(`${e.message}\n`);
+            code = 2;
+            continue;
+        }
+        const result = await checkFlowInProject({
+            projectDir,
+            flow,
+            unsupported: options.unsupported,
+            ...(options.environment && { environment: options.environment }),
+        });
+        const problems = result.problems.map((p) => describe(result.flow, p));
+        all.push(...problems);
+        if (code === 0 && problems.some((p) => p.level === "error"))
+            code = 1;
+        if (!options.json) {
+            io.out(problems.length === 0
+                ? `${flow.id}: ok\n`
+                : `${flow.id}:\n${problemLines(io, problems)}`);
+        }
+    }
+    if (options.json)
+        io.out(`${JSON.stringify(all, null, 2)}\n`);
+    return code;
+}
+async function run(refs, io, options) {
+    const projectDir = process.cwd();
+    const flows = [];
+    for (const ref of refs)
+        flows.push(await load(projectDir, ref));
+    const refuse = (problems, flow) => {
+        const described = problems.map((p) => describe(flow, p));
+        if (options.json)
+            io.out(`${JSON.stringify(described, null, 2)}\n`);
+        else
+            io.err(`${flow.id} can't run:\n${problemLines(io, described)}Nothing was run.\n`);
+        return 2;
+    };
+    // 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 errors = problems.filter((p) => p.level === "error");
+            if (errors.length)
+                return refuse(errors, flow);
+        }
+    }
+    let code = 0;
+    for (const flow of flows) {
+        if (io.signal?.aborted) {
+            code = 1;
+            break;
+        }
+        const builder = new FlowReportBuilder(flow);
+        const human = options.json
+            ? undefined
+            : new FlowReporter({ flow, write: io.out, color: io.color });
+        if (flows.indexOf(flow) > 0 && !options.json)
+            io.out("\n");
+        let summary;
+        try {
+            summary = await runFlowInProject({
+                ...options.run,
+                projectDir,
+                flow,
+                unsupported: options.unsupported,
+                ...(io.signal && { signal: io.signal }),
+                onEvent: (event) => {
+                    builder.handle(event);
+                    if (options.json)
+                        io.out(`${JSON.stringify(event)}\n`);
+                    else
+                        human?.handle(event);
+                },
+            });
+        }
+        catch (e) {
+            if (e instanceof FlowCheckError)
+                return refuse(e.problems, flow);
+            throw e;
+        }
+        const file = await writeFlowReport(projectDir, builder.finish(summary));
+        if (!options.json)
+            io.out(`Report: ${path.relative(projectDir, file) || file}\n`);
+        if (summary.status !== "passed")
+            code = 1;
+    }
+    return code;
+}
+/** `samurai flow ...`: `argv` is what follows `flow`. Returns the exit code */
+export async function flowCommand(argv, io) {
+    const { values, positionals } = parseCommandLine(argv);
+    const [sub, ...refs] = positionals;
+    const unsupported = values["allow-unsupported"] ? "skip" : "fail";
+    const json = values.json === true;
+    const overrides = parseRunOverrides(argv, io.env);
+    try {
+        if (sub === "list" && refs.length === 0)
+            return await list(io, json);
+        if (sub === "check")
+            return await check(refs, io, {
+                json,
+                unsupported,
+                ...(overrides.environment && { environment: overrides.environment }),
+            });
+        if (sub === "run") {
+            if (values.all && refs.length > 0)
+                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 targets = values.all ? await everyFlow(process.cwd()) : refs;
+            return await run(targets, io, {
+                json,
+                unsupported,
+                ...(overrides.environment && { environment: overrides.environment }),
+                run: {
+                    ...overrides,
+                    ...(flags.headless !== undefined && { headless: flags.headless }),
+                    ...(flags.port !== undefined && { port: flags.port }),
+                },
+            });
+        }
+        throw new UsageError(sub === undefined
+            ? "Which flow command?"
+            : `Unknown flow command "${[sub, ...refs].join(" ")}"`);
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            io.err(`${e.message}\n\n${FLOW_USAGE}`);
+            return 2;
+        }
+        throw e;
+    }
+}

package/dist/cli/main.d.ts

@@ -1,4 +1,4 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n\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  --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.\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\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 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 { flowCommand } from "./flow.js";
 import { initProject } from "./init.js";
 export const USAGE = `samurai: browser tests over WebDriver BiDi
 
@@ -12,11 +13,13 @@ Usage:
   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)
 
 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:
@@ -37,6 +40,14 @@ Options for record (also --env, --port, --json):
   -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.
+
 Run it in the project folder, the one holding samurai.config.ts.
 `;
 function version() {
@@ -59,6 +70,8 @@ export async function main(argv, io) {
             io.out(`${version()}\n`);
             return 0;
         }
+        if (command === "flow")
+            return await flowCommand(rest, io);
         if (command === "init") {
             const { written, skipped } = initProject(positionals[0] ?? ".");
             for (const file of written)
@@ -124,6 +137,7 @@ export async function main(argv, io) {
             ...(flags.headless !== undefined && { headless: flags.headless }),
             ...(flags.port !== undefined && { port: flags.port }),
             ...(flags.grep !== undefined && { grep: flags.grep }),
+            ...(flags.group !== undefined && { group: flags.group }),
             ...(flags.files && { files: flags.files }),
         };
         if (command === "list") {

package/dist/flows/core/check.d.ts

@@ -0,0 +1,45 @@
+import { type FlowProblem } from "./nodes/index.js";
+import type { AnyNodeDefinition } from "./nodes/define.js";
+import type { FlowFile, FlowNodeModel } from "./schema.js";
+export type { FlowProblem } from "./nodes/index.js";
+export interface CheckOptions {
+    /** The test ids that exist. When given, a Test node whose test is gone is an error. */
+    tests?: Iterable<string>;
+    /** The group names that exist. When given, a Group node whose group is gone is an error. */
+    groups?: Iterable<string>;
+    /** The environment expressions are checked against (its name and variable names). Without it, expressions are not checked, only left empty. */
+    environment?: {
+        name: string;
+        variables: Record<string, unknown>;
+    };
+    /**
+     * The kinds that have a handler. When given, every step or branches node of
+     * another kind is reported as unsupported:
+     *  - `unsupported: "skip"` (default): a warning, `<label> nodes can't run yet. They are skipped.`
+     *  - `unsupported: "fail"`: an error, `<label> can't run yet.`
+     * Without `handled` nothing is reported.
+     */
+    handled?: ReadonlySet<string>;
+    unsupported?: "skip" | "fail";
+    /**
+     * How a node is named in every message (reachability, leads-to-End, branches,
+     * "needs at least N branches"). When it returns a string, that is the name; when it
+     * returns `undefined`, the node's title, else its key, else its kind's label is used.
+     * The SAMURAI app passes the editor's titles (a Test node shows its test's name).
+     */
+    titles?: (node: FlowNodeModel) => string | undefined;
+    /** Definitions of kinds core doesn't have (steps). A node of a kind in neither is "Unknown step". */
+    nodes?: readonly AnyNodeDefinition[];
+}
+/**
+ * Checks a flow before a run: the shape of the graph, keys, references that still
+ * exist, expressions, and what a run can't execute. Pure; returns every problem.
+ * Messages are the SAMURAI app's, except that a node is named by its `title`, else
+ * its key, else its kind's label (the app names it by what the editor shows).
+ */
+export declare function checkFlow(flow: FlowFile, options?: CheckOptions): FlowProblem[];
+/** Every expression field that doesn't check out, as "Label: message" */
+export declare function expressionProblems(flow: FlowFile, environment: {
+    name: string;
+    variables: Record<string, unknown>;
+}, nodes?: readonly AnyNodeDefinition[]): FlowProblem[];