@itmetsam/samurai-framework 0.20.0 → 0.21.1

package/dist/flows/run/branch-context.js

@@ -1,23 +1,25 @@
 import { isDeepStrictEqual } from "node:util";
-export function forkContext(context) {
+export function forkContext(context, outputsById) {
     return {
         context: {
             ...context,
             vars: { ...context.vars },
             nodes: { ...context.nodes },
         },
+        outputsById: { ...outputsById },
         base: { ...context.vars },
     };
 }
 /**
- * Takes what the branches wrote into `into`: every node output, and every variable a branch changed. A variable
+ * Takes what the branches wrote into `into` and `intoOutputs`: 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 function mergeForks(into, forks) {
+export function mergeForks(into, intoOutputs, forks) {
     const changed = new Map();
     const clashes = new Set();
-    for (const { context, base } of forks) {
+    for (const { context, outputsById, base } of forks) {
         Object.assign(into.nodes, context.nodes);
+        Object.assign(intoOutputs, outputsById);
         for (const [name, value] of Object.entries(context.vars)) {
             if (name in base && isDeepStrictEqual(base[name], value))
                 continue;

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

@@ -1,4 +1,5 @@
 import type { RunEvent } from "../../runner/reporter.js";
+import type { SupportedBrowser } from "../../types/browser.js";
 export type NodeStatus = "passed" | "failed" | "skipped" | "not-run";
 export interface NodeResult {
     status: NodeStatus;
@@ -10,32 +11,46 @@ export interface NodeResult {
     branch?: string;
     /** What the node wrote to vars */
     wrote?: Record<string, unknown>;
-    /** A step's outputs, readable later as `nodes.<key>.<name>` */
+    /** A step's outputs, or the outputs a Test node's test saved; readable later as `nodes.<key>.<name>` */
     outputs?: Record<string, unknown>;
+    /** A Test or Group node: the input values it sent to its tests; absent when it sent none */
+    inputs?: Record<string, string>;
 }
 /** One test of a node: absolute file and full name */
 export interface NodeTest {
     file: string;
     name: string;
 }
+/**
+ * What a flow run reports. A flow runs once per browser: every event but the last carries the browser of its run,
+ * `flow-start` and `flow-end` come once per browser, and `flow-done` closes the whole thing.
+ */
 export type FlowEvent = {
     type: "flow-start";
+    browser: SupportedBrowser;
     environment: string;
 } | {
     type: "node-start";
+    browser: SupportedBrowser;
     nodeId: string;
 } | {
     type: "node-end";
+    browser: SupportedBrowser;
     nodeId: string;
     result: NodeResult;
 } | {
     type: "test";
+    browser: SupportedBrowser;
     nodeId: string;
     event: RunEvent;
 } | {
     type: "flow-end";
+    browser: SupportedBrowser;
     summary: FlowSummary;
-};
+} | ({
+    type: "flow-done";
+} & FlowRunResult);
+/** How one browser's walk of a flow ended */
 export interface FlowSummary {
     status: "passed" | "failed" | "cancelled";
     nodes: Record<string, NodeResult>;
@@ -43,3 +58,16 @@ export interface FlowSummary {
     /** The flow couldn't be walked at all */
     error?: string;
 }
+/** One browser's run of a flow */
+export interface FlowBrowserRun {
+    browser: SupportedBrowser;
+    summary: FlowSummary;
+}
+/**
+ * How a flow run ended, across its browsers: `cancelled` when it was aborted, else `failed` when any run failed,
+ * else `passed`. `runs` holds the runs that started, in the order they ran; an abort leaves the rest out
+ */
+export interface FlowRunResult {
+    status: "passed" | "failed" | "cancelled";
+    runs: FlowBrowserRun[];
+}

package/dist/flows/run/handlers/group.js

@@ -1,7 +1,11 @@
-import { runNodeTests } from "./support.js";
+import { runWiredTests } from "../node-inputs.js";
+import { notInBrowser } from "./support.js";
 export const group = async (node, run) => {
+    const skipped = notInBrowser(node, run);
+    if (skipped)
+        return skipped;
     const list = run.nodeTests[node.id] ?? [];
     if (list.length === 0)
         return { status: "passed", note: "This group has no tests." };
-    return runNodeTests(node, run, list);
+    return runWiredTests(node, run, list);
 };

package/dist/flows/run/handlers/support.d.ts

@@ -2,7 +2,12 @@ import { type FlowNodeModel } from "../../core/index.js";
 import type { NodeTest } from "../events.js";
 import type { HandlerRun, Outcome } from "./types.js";
 export declare const fail: (e: unknown) => Outcome;
-/** Runs `list` for the node and turns the result into an outcome */
-export declare function runNodeTests(node: FlowNodeModel, run: HandlerRun, list: NodeTest[]): Promise<Outcome>;
+/** A Test or Group node whose browsers lack the run's is skipped with a note */
+export declare const notInBrowser: (node: FlowNodeModel, run: HandlerRun) => Outcome | undefined;
+/**
+ * Runs `list` for the node with `inputs` and turns the result into an outcome: the inputs it sent (when any) and,
+ * for a Test node that passed, the outputs its test saved (a retried test's last attempt)
+ */
+export declare function runNodeTests(node: FlowNodeModel, run: HandlerRun, list: NodeTest[], inputs?: Record<string, string>): Promise<Outcome>;
 /** The checker's problem with an expression, as the builder would show it: a bypassed check fails the node the same way */
 export declare const problemAt: (node: FlowNodeModel, run: HandlerRun, text: string) => string | undefined;

package/dist/flows/run/handlers/support.js

@@ -3,20 +3,49 @@ export const fail = (e) => ({
     status: "failed",
     error: e.message,
 });
-/** Runs `list` for the node and turns the result into an outcome */
-export async function runNodeTests(node, run, list) {
+/** A Test or Group node whose browsers lack the run's is skipped with a note */
+export const notInBrowser = (node, run) => run.nodeBrowsers?.[node.id]?.includes(run.browser) === false
+    ? { status: "skipped", note: `not run in ${run.browser}` }
+    : undefined;
+/**
+ * Runs `list` for the node with `inputs` and turns the result into an outcome: the inputs it sent (when any) and,
+ * for a Test node that passed, the outputs its test saved (a retried test's last attempt)
+ */
+export async function runNodeTests(node, run, list, inputs = {}) {
+    const sent = Object.keys(inputs).length > 0 ? inputs : undefined;
+    let saved;
     let result;
     try {
-        result = await run.runTests(node.id, list, (e) => run.onTestEvent(node.id, e), run.nodeBrowsers?.[node.id]);
+        result = await run.runTests(node.id, list, (e) => {
+            if (e.type === "test-end")
+                saved = "outputs" in e.result ? e.result.outputs : undefined;
+            run.onTestEvent(node.id, e);
+        }, sent);
     }
     catch (e) {
-        return fail(e);
+        return {
+            status: "failed",
+            error: e.message,
+            ...(sent && { inputs: sent }),
+        };
     }
     if (result === "cancelled")
         return "cancelled";
+    const outputs = node.kind === "test" ? saved : undefined;
     return result === "passed"
-        ? { status: "passed" }
-        : { status: "failed", error: "A test failed." };
+        ? {
+            status: "passed",
+            ...(sent && { inputs: sent }),
+            ...(outputs && { outputs }),
+        }
+        : {
+            status: "failed",
+            error: "A test failed.",
+            ...(sent && { inputs: sent }),
+        };
 }
 /** The checker's problem with an expression, as the builder would show it: a bypassed check fails the node the same way */
-export const problemAt = (node, run, text) => checkExpression(parseExpression(text), scopeAt(run.flow, node.id, run.environment, run.nodes))?.message;
+export const problemAt = (node, run, text) => checkExpression(parseExpression(text), scopeAt(run.flow, node.id, run.environment, {
+    nodes: run.nodes,
+    ...(run.facts && { facts: run.facts }),
+}))?.message;

package/dist/flows/run/handlers/test.js

@@ -1,7 +1,11 @@
-import { runNodeTests } from "./support.js";
+import { runWiredTests } from "../node-inputs.js";
+import { notInBrowser } from "./support.js";
 export const test = async (node, run) => {
+    const skipped = notInBrowser(node, run);
+    if (skipped)
+        return skipped;
     const list = run.nodeTests[node.id];
     if (!list || list.length === 0)
         return { status: "failed", error: "This test was deleted or moved." };
-    return runNodeTests(node, run, list);
+    return runWiredTests(node, run, list);
 };

package/dist/flows/run/handlers/types.d.ts

@@ -1,4 +1,5 @@
-import type { AnyNodeDefinition, ExpressionContext, FlowFile, FlowNodeModel } from "../../core/index.js";
+import type { AnyNodeDefinition, ExpressionContext, FlowFacts, FlowFile, FlowNodeModel } from "../../core/index.js";
+import type { OutputsById } from "../branch-context.js";
 import type { RunEvent } from "../../../runner/reporter.js";
 import type { SupportedBrowser } from "../../../types/browser.js";
 import type { NodeResult, NodeTest } from "../events.js";
@@ -10,11 +11,18 @@ export interface HandlerRun {
         variables: Record<string, unknown>;
     };
     context: ExpressionContext;
+    /** The outputs the nodes that ran saved, by node id: where wired inputs come from */
+    outputsById: OutputsById;
+    /** The project's tests' inputs and outputs and its groups' tests; without them no input is wired */
+    facts?: FlowFacts;
     nodeTests: Record<string, NodeTest[]>;
-    /** The browsers of the nodes that have their own (a Group node's group); the others use the project's */
+    /** The browser this run is in: a flow runs once per browser */
+    browser: SupportedBrowser;
+    /** The browsers each node runs in; a node not listed runs in every one */
     nodeBrowsers?: Record<string, SupportedBrowser[]>;
     signal: AbortSignal;
-    runTests: (nodeId: string, tests: NodeTest[], onEvent: (e: RunEvent) => void, browsers?: SupportedBrowser[]) => Promise<"passed" | "failed" | "cancelled">;
+    /** Runs a node's tests in `browser`, with values for their inputs */
+    runTests: (nodeId: string, tests: NodeTest[], onEvent: (e: RunEvent) => void, inputs?: Record<string, string>) => Promise<"passed" | "failed" | "cancelled">;
     sleep: (ms: number, signal: AbortSignal) => Promise<void>;
     onTestEvent: (nodeId: string, e: RunEvent) => void;
     /** Definitions of kinds core doesn't have (steps), for expression scopes */

package/dist/flows/run/node-folder.d.ts

@@ -1,5 +1,10 @@
+import type { RunEvent } from "../../runner/reporter.js";
+import type { SupportedBrowser } from "../../types/browser.js";
 /**
- * The folder a flow node's screenshots go in, relative to `runFlowInProject`'s `outputDir`, with `/` separators:
- * `nodes/` and the node id cleaned for a file name. A node's screenshot paths are relative to this folder.
+ * The folder a flow node writes to in one browser's run, relative to `runFlowInProject`'s `outputDir`, with `/`
+ * separators: the browser, `nodes/` and the node id cleaned for a file name. A node's screenshot paths already
+ * start with it (they are relative to `outputDir`), so an app needs this only to show or open the folder.
  */
-export declare function nodeFolder(nodeId: string): string;
+export declare function nodeFolder(nodeId: string, browser: SupportedBrowser): string;
+/** A node's test event with its screenshot paths (relative to the node's folder) made relative to `outputDir` */
+export declare function inNodeFolder(event: RunEvent, folder: string): RunEvent;

package/dist/flows/run/node-folder.js

@@ -1,8 +1,32 @@
 import { cleanName } from "../../browser/evidence.js";
 /**
- * The folder a flow node's screenshots go in, relative to `runFlowInProject`'s `outputDir`, with `/` separators:
- * `nodes/` and the node id cleaned for a file name. A node's screenshot paths are relative to this folder.
+ * The folder a flow node writes to in one browser's run, relative to `runFlowInProject`'s `outputDir`, with `/`
+ * separators: the browser, `nodes/` and the node id cleaned for a file name. A node's screenshot paths already
+ * start with it (they are relative to `outputDir`), so an app needs this only to show or open the folder.
  */
-export function nodeFolder(nodeId) {
-    return `nodes/${cleanName(nodeId)}`;
+export function nodeFolder(nodeId, browser) {
+    return `${browser}/nodes/${cleanName(nodeId)}`;
+}
+const withFolder = (result, folder) => "screenshots" in result && result.screenshots
+    ? {
+        ...result,
+        screenshots: result.screenshots.map((s) => ({
+            ...s,
+            path: `${folder}/${s.path}`,
+        })),
+    }
+    : result;
+/** A node's test event with its screenshot paths (relative to the node's folder) made relative to `outputDir` */
+export function inNodeFolder(event, folder) {
+    if (event.type === "test-end")
+        return { ...event, result: withFolder(event.result, folder) };
+    if (event.type === "run-end")
+        return {
+            ...event,
+            summary: {
+                ...event.summary,
+                tests: event.summary.tests.map((t) => withFolder(t, folder)),
+            },
+        };
+    return event;
 }

package/dist/flows/run/node-inputs.d.ts

@@ -0,0 +1,5 @@
+import { type FlowNodeModel } from "../core/index.js";
+import type { NodeTest } from "./events.js";
+import type { HandlerRun, Outcome } from "./handlers/types.js";
+/** Runs a Test or Group node's tests with the inputs it resolves; an input that can't be resolved fails the node */
+export declare function runWiredTests(node: FlowNodeModel, run: HandlerRun, list: NodeTest[]): Promise<Outcome>;

package/dist/flows/run/node-inputs.js

@@ -0,0 +1,62 @@
+import { evaluateText, wiringAt } from "../core/index.js";
+import { problemAt, runNodeTests } from "./handlers/support.js";
+/** What a node's title is in a message: its title, else its key, else its id */
+const titleOf = (node, id) => node?.title || node?.key || id;
+/** The value of an override expression as an input: text as is, a number or a boolean as text, else an error */
+function expressionValue(node, run, expression) {
+    const problem = problemAt(node, run, expression);
+    if (problem)
+        return { error: problem };
+    let value;
+    try {
+        value = evaluateText(expression, run.context);
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+    if (typeof value === "string")
+        return { value };
+    if (typeof value === "number" || typeof value === "boolean")
+        return { value: String(value) };
+    return { error: "the expression gave no text" };
+}
+/**
+ * The values a Test or Group node sends for its inputs, by `wiringAt`: an earlier node's saved output, an override
+ * expression's value, nothing for "use the default". An input whose source saved nothing, an override that gives
+ * no text, or an input with no source is an error, and the node's tests must not run.
+ */
+function resolveNodeInputs(node, run) {
+    const inputs = {};
+    const wiring = wiringAt(run.flow, node.id, {
+        ...(run.facts && { facts: run.facts }),
+    });
+    for (const [name, source] of Object.entries(wiring)) {
+        if (source.from === "default")
+            continue;
+        if (source.from === "none")
+            return { error: `input "${name}" has no source` };
+        if (source.from === "node") {
+            const value = run.outputsById[source.nodeId]?.[source.output];
+            if (typeof value !== "string") {
+                const producer = run.flow.nodes.find((n) => n.id === source.nodeId);
+                return {
+                    error: `input "${name}": ${titleOf(producer, source.nodeId)} saved no ${source.output}`,
+                };
+            }
+            inputs[name] = value;
+            continue;
+        }
+        const result = expressionValue(node, run, source.expression);
+        if ("error" in result)
+            return { error: `input "${name}": ${result.error}` };
+        inputs[name] = result.value;
+    }
+    return { inputs };
+}
+/** Runs a Test or Group node's tests with the inputs it resolves; an input that can't be resolved fails the node */
+export function runWiredTests(node, run, list) {
+    const resolved = resolveNodeInputs(node, run);
+    if ("error" in resolved)
+        return Promise.resolve({ status: "failed", error: resolved.error });
+    return runNodeTests(node, run, list, resolved.inputs);
+}

package/dist/flows/run/node-pool.d.ts

@@ -3,7 +3,7 @@ import type { WorkerPool } from "../../runner/worker-pool.js";
 import type { WorkItem } from "../../runner/worker-protocol.js";
 import type { SupportedBrowser } from "../../types/browser.js";
 import type { NodeTest } from "./events.js";
-/** The work items of a node: each test in each browser, the browsers one after the other */
-export declare function itemsOf(tests: NodeTest[], browsers: readonly SupportedBrowser[], outputDir?: string): WorkItem[];
+/** The work items of a node in one browser's run: each of its tests, in that browser, with the node's inputs */
+export declare function itemsOf(tests: NodeTest[], browser: SupportedBrowser, outputDir?: string, inputs?: Record<string, string>): WorkItem[];
 /** Runs the tests of a node on the pool and reports them as a run would */
 export declare function runOnPool(pool: Pick<WorkerPool, "run">, items: WorkItem[], onEvent: (event: RunEvent) => void, signal: AbortSignal): Promise<"passed" | "failed" | "cancelled">;

package/dist/flows/run/node-pool.js

@@ -1,13 +1,13 @@
-/** The work items of a node: each test in each browser, the browsers one after the other */
-export function itemsOf(tests, browsers, outputDir) {
-    return browsers
-        .flatMap((browser) => tests.map((t) => ({
+/** The work items of a node in one browser's run: each of its tests, in that browser, with the node's inputs */
+export function itemsOf(tests, browser, outputDir, inputs) {
+    return tests.map((t, index) => ({
+        index,
         file: t.file,
         testName: t.name,
         browser,
         ...(outputDir !== undefined && { outputDir }),
-    })))
-        .map((item, index) => ({ ...item, index }));
+        ...(inputs && { inputs }),
+    }));
 }
 /** Runs the tests of a node on the pool and reports them as a run would */
 export async function runOnPool(pool, items, onEvent, signal) {

package/dist/flows/run/node-runner.d.ts

@@ -0,0 +1,24 @@
+import type { runTests } from "../../runner/run.js";
+import type { WorkerPool } from "../../runner/worker-pool.js";
+import type { SupportedBrowser } from "../../types/browser.js";
+import type { SamuraiTestConfig } from "../../types/config.js";
+import type { RunFlowInProjectOptions } from "./project-options.js";
+import type { RunFlowOptions } from "./run.js";
+/** What every node's tests share in a project's flow run */
+export interface NodeRunnerInput {
+    projectDir: string;
+    config: SamuraiTestConfig;
+    options: RunFlowInProjectOptions;
+    /** The environment the expressions see, when the project defines it */
+    environment?: string;
+    retries: number;
+    run: typeof runTests;
+    /** The run's worker pool, when `workers` is above 1 */
+    pool?: Pick<WorkerPool, "run">;
+}
+/**
+ * How a Test or Group node runs its tests in one browser's run of a project's flow: on the pool, else through
+ * `runTests` in this process. With an `outputDir`, each node writes to its own `nodeFolder` in it, and its
+ * screenshot paths are made relative to `outputDir`.
+ */
+export declare function nodeRunner(input: NodeRunnerInput, browser: SupportedBrowser): RunFlowOptions["runTests"];

package/dist/flows/run/node-runner.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { inNodeFolder, nodeFolder } from "./node-folder.js";
+import { itemsOf, runOnPool } from "./node-pool.js";
+/**
+ * How a Test or Group node runs its tests in one browser's run of a project's flow: on the pool, else through
+ * `runTests` in this process. With an `outputDir`, each node writes to its own `nodeFolder` in it, and its
+ * screenshot paths are made relative to `outputDir`.
+ */
+export function nodeRunner(input, browser) {
+    const { projectDir, config, options, environment, retries, run, pool } = input;
+    return async ({ nodeId, tests, onEvent: onTestEvent, signal, inputs }) => {
+        // Each node gets a folder of its own per browser: the same test in two nodes would overwrite its screenshots
+        const folder = nodeFolder(nodeId, browser);
+        const outputDir = options.outputDir !== undefined
+            ? path.join(options.outputDir, ...folder.split("/"))
+            : undefined;
+        // Screenshot paths come relative to the node's folder: make them relative to outputDir
+        const onEvent = outputDir !== undefined
+            ? (e) => onTestEvent(inNodeFolder(e, folder))
+            : onTestEvent;
+        if (pool)
+            return runOnPool(pool, itemsOf(tests, browser, outputDir, inputs), onEvent, signal);
+        const summary = await run({
+            projectDir,
+            config,
+            ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
+            ...(environment !== undefined && { environment }),
+            ...(options.headless !== undefined && { headless: options.headless }),
+            ...(options.timeout !== undefined && { timeout: options.timeout }),
+            ...(options.expectTimeout !== undefined && {
+                expectTimeout: options.expectTimeout,
+            }),
+            ...(options.port !== undefined && { port: options.port }),
+            ...(retries > 0 && { retries }),
+            browsers: [browser],
+            files: [...new Set(tests.map((t) => t.file))],
+            testNames: tests.map((t) => t.name),
+            ...(inputs && { inputs }),
+            reportPath: false,
+            ...(outputDir !== undefined && { outputDir }),
+            signal,
+            onEvent,
+        });
+        if (signal.aborted)
+            return "cancelled";
+        return summary.status === "success" ? "passed" : "failed";
+    };
+}

package/dist/flows/run/per-browser.d.ts

@@ -0,0 +1,21 @@
+import type { FlowFile } from "../core/index.js";
+import type { SupportedBrowser } from "../../types/browser.js";
+import type { FlowEvent, FlowRunResult, FlowSummary } from "./events.js";
+/**
+ * The browsers a flow runs in, one run each: the union of its nodes' browsers (`nodeBrowsers`, a Test node's
+ * the project's and a Group node's its group's), in the order the flow's nodes first name them. `only` keeps
+ * those of its browsers, in the flow's order; one no node uses is ignored, and none left is an error. A flow
+ * without Test or Group nodes runs once, in the first of `only`, else the first of `projectBrowsers`.
+ */
+export declare function flowBrowsers(nodeBrowsers: Record<string, readonly SupportedBrowser[]>, flow: Pick<FlowFile, "nodes">, projectBrowsers: readonly SupportedBrowser[], only?: readonly SupportedBrowser[]): SupportedBrowser[];
+/**
+ * Walks the flow once per browser, one after the other, then sends `flow-done`. The runs are independent: a
+ * failed one (an `onFailure: "stop"` included) ends that browser's run only. An abort stops them all: the runs
+ * left are not started. The result is cancelled only when a run was cut short or a browser was not started.
+ */
+export declare function runPerBrowser(input: {
+    browsers: readonly SupportedBrowser[];
+    walk: (browser: SupportedBrowser) => Promise<FlowSummary>;
+    signal?: AbortSignal;
+    onEvent?: (event: FlowEvent) => void;
+}): Promise<FlowRunResult>;

package/dist/flows/run/per-browser.js

@@ -0,0 +1,46 @@
+/**
+ * The browsers a flow runs in, one run each: the union of its nodes' browsers (`nodeBrowsers`, a Test node's
+ * the project's and a Group node's its group's), in the order the flow's nodes first name them. `only` keeps
+ * those of its browsers, in the flow's order; one no node uses is ignored, and none left is an error. A flow
+ * without Test or Group nodes runs once, in the first of `only`, else the first of `projectBrowsers`.
+ */
+export function flowBrowsers(nodeBrowsers, flow, projectBrowsers, only) {
+    const union = [
+        ...new Set(flow.nodes.flatMap((n) => nodeBrowsers[n.id] ?? [])),
+    ];
+    if (union.length === 0)
+        return [only?.[0] ?? projectBrowsers[0]];
+    if (!only)
+        return union;
+    const kept = union.filter((b) => only.includes(b));
+    if (kept.length === 0)
+        throw new Error(`runFlowInProject(): this flow runs in none of ${only.join(", ")}`);
+    return kept;
+}
+/**
+ * Walks the flow once per browser, one after the other, then sends `flow-done`. The runs are independent: a
+ * failed one (an `onFailure: "stop"` included) ends that browser's run only. An abort stops them all: the runs
+ * left are not started. The result is cancelled only when a run was cut short or a browser was not started.
+ */
+export async function runPerBrowser(input) {
+    const runs = [];
+    for (const browser of input.browsers) {
+        if (input.signal?.aborted)
+            break;
+        const summary = await input.walk(browser);
+        runs.push({ browser, summary });
+        if (summary.status === "cancelled")
+            break;
+    }
+    // An abort that came after every run finished cuts nothing short
+    const cutShort = runs.length < input.browsers.length ||
+        runs.some((r) => r.summary.status === "cancelled");
+    const status = cutShort
+        ? "cancelled"
+        : runs.some((r) => r.summary.status === "failed")
+            ? "failed"
+            : "passed";
+    const result = { status, runs };
+    input.onEvent?.({ type: "flow-done", ...result });
+    return result;
+}

package/dist/flows/run/project-facts.d.ts

@@ -0,0 +1,13 @@
+import { type FlowFacts } from "../core/index.js";
+import type { ResolvedGroup } from "../../runner/groups.js";
+/** What `flowFacts` needs of a project's test, as the runner registers it */
+interface TestIO {
+    id: string;
+    /** The inputs the test declares, with their defaults */
+    inputs?: Record<string, string>;
+    /** The outputs the test declares */
+    outputs?: string[];
+}
+/** The facts a flow is checked and wired with: each test's declared inputs and outputs, and each group's tests */
+export declare function flowFacts(tests: readonly TestIO[], groups: readonly Pick<ResolvedGroup, "name" | "testIds">[]): FlowFacts;
+export {};

package/dist/flows/run/project-facts.js

@@ -0,0 +1,12 @@
+import { flowFactsFrom } from "../core/index.js";
+/** The facts a flow is checked and wired with: each test's declared inputs and outputs, and each group's tests */
+export function flowFacts(tests, groups) {
+    return flowFactsFrom(tests.map((t) => ({
+        id: t.id,
+        inputs: Object.entries(t.inputs ?? {}).map(([name, value]) => ({
+            name,
+            default: value,
+        })),
+        ...(t.outputs && { outputs: t.outputs }),
+    })), groups);
+}

package/dist/flows/run/project-options.d.ts

@@ -3,6 +3,7 @@ import type { PoolOptions, WorkerPool } from "../../runner/worker-pool.js";
 import type { runTests } from "../../runner/run.js";
 import type { FlowFile, FlowProblem } from "../core/index.js";
 import type { FlowEvent } from "./events.js";
+import type { SupportedBrowser } from "../../types/browser.js";
 /** The flow has errors; nothing was run */
 export declare class FlowCheckError extends Error {
     readonly problems: FlowProblem[];
@@ -20,10 +21,16 @@ export interface RunFlowInProjectOptions extends ProjectOptions {
     /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
     unsupported?: "fail" | "skip";
     port?: number;
+    /**
+     * Run the flow in these browsers only, in the flow's order (a browser no node uses is ignored, none left is an
+     * error). Unset runs it once in each browser its nodes use (see `flowBrowsers`); `[one]` runs it once
+     */
+    browsers?: SupportedBrowser[];
     /**
      * The folder for the tests' named screenshots, instead of `<project>/result` (see `runTests`). Each node writes to
-     * `nodes/<node id>/` inside it, so a test that runs in two nodes keeps both sets; screenshot paths in a node's
-     * results are relative to that folder. Relative to the project folder
+     * `<browser>/nodes/<node id>/` inside it (`nodeFolder`), so a test that runs in two nodes or two browsers keeps
+     * every set; screenshot paths in a node's test events start with that folder: they are relative to `outputDir`,
+     * with `/` separators. Relative to the project folder
      */
     outputDir?: string;
     /**

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

@@ -1,7 +1,7 @@
 import { type FlowFile, type FlowProblem } from "../core/index.js";
 import { type ResolvedGroup } from "../../runner/groups.js";
 import type { SamuraiTestConfig } from "../../types/config.js";
-import type { FlowSummary, NodeTest } from "./events.js";
+import type { FlowRunResult, NodeTest } from "./events.js";
 import { FlowCheckError, type FlowRunOptions, type RunFlowInProjectOptions } from "./project-options.js";
 import type { SupportedBrowser } from "../../types/browser.js";
 export { FlowCheckError };
@@ -15,15 +15,19 @@ interface ProjectTest {
     name: string;
     /** The spec file relative to `srcDir`, with `/` separators */
     relative: string;
+    /** The inputs the test declares, with their defaults */
+    inputs?: Record<string, string>;
+    /** The outputs the test declares */
+    outputs?: string[];
 }
-/** The tests, and the browsers, of each Test and Group node of a flow; a Test node uses the project's browsers */
-export declare function nodeTestsOf(flow: FlowFile, tests: Pick<ProjectTest, "id" | "file" | "name">[], groups: Pick<ResolvedGroup, "name" | "testIds" | "browsers">[]): {
+/** The tests, and the browsers, of each Test and Group node of a flow: a Test node's are the project's, a Group node's its group's */
+export declare function nodeTestsOf(flow: FlowFile, tests: Pick<ProjectTest, "id" | "file" | "name">[], groups: Pick<ResolvedGroup, "name" | "testIds" | "browsers">[], projectBrowsers: SupportedBrowser[]): {
     nodeTests: Record<string, NodeTest[]>;
     nodeBrowsers: Record<string, SupportedBrowser[]>;
 };
 /**
  * Checks a flow against the project without running it: its tests, groups and environment
- * variables, and which kinds can run. Returns the flow (with keys) and every problem, warnings included.
+ * variables, which kinds can run, and where each Test and Group node's inputs come from. Returns the flow (with keys) and every problem, warnings included.
  */
 export declare function checkFlowInProject(options: Pick<RunFlowInProjectOptions, "flow" | "flowId" | "projectDir" | "config" | "dataDir" | "environment" | "unsupported">): Promise<{
     flow: FlowFile;
@@ -31,8 +35,9 @@ export declare function checkFlowInProject(options: Pick<RunFlowInProjectOptions
 }>;
 /**
  * Checks and runs a flow of a project: loads its config, lists its tests and groups, refuses to start
- * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow; each Test and Group node runs
- * its tests through `runTests`, one after the other, or on one shared worker pool when `workers` is above 1.
- * One at a time per process.
+ * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow once per browser (see `flowBrowsers`),
+ * one browser after the other, each run with its own variables and results. Each Test and Group node runs its
+ * tests through `runTests`, one after the other, or on one shared worker pool when `workers` is above 1.
+ * Resolves to every run's summary; the last event is `flow-done`. One at a time per process.
  */
-export declare function runFlowInProject(options: RunFlowInProjectOptions): Promise<FlowSummary>;
+export declare function runFlowInProject(options: RunFlowInProjectOptions): Promise<FlowRunResult>;