@itmetsam/samurai-framework 0.10.0 → 0.12.0

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

@@ -1,2 +1,2 @@
-import { type Handler } from "./support.js";
+import type { Handler } from "./types.js";
 export declare const group: Handler;

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

@@ -1,4 +1,4 @@
-import type { Handler } from "./support.js";
-export type { Handler, HandlerRun, Outcome } from "./support.js";
+import type { Handler } from "./types.js";
+export type { Handler, HandlerRun, Outcome } from "./types.js";
 /** The kinds a run can execute, by kind: the closed ones and every built-in step */
 export declare const HANDLERS: Readonly<Record<string, Handler>>;

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

@@ -1,3 +1,3 @@
-import type { Handler } from "./support.js";
+import type { Handler } from "./types.js";
 /** Its branches are walked by the walker; the node itself just opens them */
 export declare const parallel: Handler;

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

@@ -1,2 +1,2 @@
-import type { Handler } from "./support.js";
+import type { Handler } from "./types.js";
 export declare const start: Handler;

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

@@ -1,30 +1,6 @@
-import { type AnyNodeDefinition, type ExpressionContext, type FlowFile, type FlowNodeModel } from "../../core/index.js";
-import type { RunEvent } from "../../../runner/reporter.js";
-import type { SupportedBrowser } from "../../../types/browser.js";
-import type { NodeResult, NodeTest } from "../events.js";
-/** What a handler can use of the run */
-export interface HandlerRun {
-    flow: FlowFile;
-    environment: {
-        name: string;
-        variables: Record<string, unknown>;
-    };
-    context: ExpressionContext;
-    nodeTests: Record<string, NodeTest[]>;
-    /** The browsers of the nodes that have their own (a Group node's group); the others use the project's */
-    nodeBrowsers?: Record<string, SupportedBrowser[]>;
-    signal: AbortSignal;
-    runTests: (tests: NodeTest[], onEvent: (e: RunEvent) => void, browsers?: SupportedBrowser[]) => 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 */
-    nodes: readonly AnyNodeDefinition[];
-    log: (nodeId: string, level: "info" | "warn" | "error", text: string) => void;
-}
-/** What a handler decides; the walker adds timing */
-export type Outcome = Omit<NodeResult, "durationMs"> | "cancelled";
-/** Runs one kind of node. A `branches` node names the branch it takes in `branch` */
-export type Handler = (node: FlowNodeModel, run: HandlerRun) => Promise<Outcome>;
+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>;

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

@@ -1,2 +1,2 @@
-import { type Handler } from "./support.js";
+import type { Handler } from "./types.js";
 export declare const test: Handler;

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

@@ -0,0 +1,27 @@
+import type { AnyNodeDefinition, ExpressionContext, FlowFile, FlowNodeModel } from "../../core/index.js";
+import type { RunEvent } from "../../../runner/reporter.js";
+import type { SupportedBrowser } from "../../../types/browser.js";
+import type { NodeResult, NodeTest } from "../events.js";
+/** What a handler can use of the run */
+export interface HandlerRun {
+    flow: FlowFile;
+    environment: {
+        name: string;
+        variables: Record<string, unknown>;
+    };
+    context: ExpressionContext;
+    nodeTests: Record<string, NodeTest[]>;
+    /** The browsers of the nodes that have their own (a Group node's group); the others use the project's */
+    nodeBrowsers?: Record<string, SupportedBrowser[]>;
+    signal: AbortSignal;
+    runTests: (tests: NodeTest[], onEvent: (e: RunEvent) => void, browsers?: SupportedBrowser[]) => 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 */
+    nodes: readonly AnyNodeDefinition[];
+    log: (nodeId: string, level: "info" | "warn" | "error", text: string) => void;
+}
+/** What a handler decides; the walker adds timing */
+export type Outcome = Omit<NodeResult, "durationMs"> | "cancelled";
+/** Runs one kind of node. A `branches` node names the branch it takes in `branch` */
+export type Handler = (node: FlowNodeModel, run: HandlerRun) => Promise<Outcome>;

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

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

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

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

package/dist/flows/run/prepare-flow.d.ts

@@ -0,0 +1,14 @@
+import { type AnyNodeDefinition, type FlowFile } from "../core/index.js";
+import type { Handler } from "./handlers/index.js";
+/** The flow's shape can't be walked (no Start, a node reached twice, a branch that never meets): the run ends with this message */
+export declare class ShapeError extends Error {
+}
+export declare const shapeError: (message: string) => ShapeError;
+/** Waits `ms`, or rejects at once when `signal` aborts */
+export declare const defaultSleep: (ms: number, signal: AbortSignal) => Promise<void>;
+/** Whether a node of this kind has a list of branches that is only known at run time (a Parallel node) */
+export declare const dynamicBranches: (def: AnyNodeDefinition) => boolean;
+/** The definition of a kind: the project's own steps first, then the built-in kinds; undefined for a kind nobody knows */
+export declare function definitionOf(nodes: readonly AnyNodeDefinition[], kind: string): AnyNodeDefinition | undefined;
+/** Throws when the flow has a step or branching node whose kind has no handler: the run would not know what to do */
+export declare function assertRunnable(flow: FlowFile, nodes: readonly AnyNodeDefinition[], handlers: Readonly<Record<string, Handler>>): void;

package/dist/flows/run/prepare-flow.js

@@ -0,0 +1,44 @@
+import { nodeDef, } from "../core/index.js";
+/** The flow's shape can't be walked (no Start, a node reached twice, a branch that never meets): the run ends with this message */
+export class ShapeError extends Error {
+}
+export const shapeError = (message) => new ShapeError(`This flow's shape can't run: ${message}`);
+/** Waits `ms`, or rejects at once when `signal` aborts */
+export const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new Error("aborted"));
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+/** Whether a node of this kind has a list of branches that is only known at run time (a Parallel node) */
+export const dynamicBranches = (def) => def.shape === "branches" && !!def.branches && !Array.isArray(def.branches);
+/** The definition of a kind: the project's own steps first, then the built-in kinds; undefined for a kind nobody knows */
+export function definitionOf(nodes, kind) {
+    const own = nodes.find((d) => d.kind === kind);
+    if (own)
+        return own;
+    try {
+        return nodeDef(kind);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Throws when the flow has a step or branching node whose kind has no handler: the run would not know what to do */
+export function assertRunnable(flow, nodes, handlers) {
+    const problems = flow.nodes
+        .map((n) => ({ n, def: definitionOf(nodes, n.kind) }))
+        .filter(({ n, def }) => def &&
+        (def.shape === "step" || def.shape === "branches") &&
+        !handlers[n.kind])
+        .map(({ def }) => `${def.label} can't run yet.`);
+    if (problems.length)
+        throw new Error(`This flow can't run: ${[...new Set(problems)].join(" ")}`);
+}

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

@@ -1,8 +1,11 @@
 import { type FlowFile, type FlowProblem } from "../core/index.js";
+import { type ResolvedGroup } from "../../runner/groups.js";
 import { type ProjectOptions } from "../../runner/project.js";
 import { runTests } from "../../runner/run.js";
+import { WorkerPool, type PoolOptions } from "../../runner/worker-pool.js";
 import type { SamuraiTestConfig } from "../../types/config.js";
-import type { FlowEvent, FlowSummary } from "./events.js";
+import type { FlowEvent, FlowSummary, NodeTest } 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,13 +23,39 @@ 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;
+    /**
+     * How many worker processes the tests of the whole run share: a number, or a percentage like `"50%"`. Unset
+     * takes `SAMURAI_WORKERS` (`workersEnv`), then the config's `workers`, then half the CPUs. 1 runs each Test
+     * and Group node through `runTests` in this process; more starts one pool that every node, and every branch
+     * of a Parallel node, takes its workers from
+     */
+    workers?: number | string;
+    /** The value of `SAMURAI_WORKERS`, when set */
+    workersEnv?: string;
+    /** @internal Replaces the worker pool (tests) */
+    createPool?: (options: PoolOptions) => Pick<WorkerPool, "run" | "dispose">;
     /** @internal Replaces the runner of each Test and Group node (tests) */
     testRunner?: typeof runTests;
     /** @internal */
     sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
 }
+/** What `runFlowInProject` takes when the flow itself is given separately: everything but `flow` and `flowId` */
+export type FlowRunOptions = Omit<RunFlowInProjectOptions, "flow" | "flowId">;
 /** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
 export declare function chooseEnvironment(config: SamuraiTestConfig, flow: FlowFile, option?: string): string;
+/** A test of the project as flows see it */
+interface ProjectTest {
+    id: string;
+    file: string;
+    name: string;
+    /** The spec file relative to `srcDir`, with `/` separators */
+    relative: 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">[]): {
+    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.
@@ -38,6 +67,8 @@ 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. One at a time per process.
+ * 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.
  */
 export declare function runFlowInProject(options: RunFlowInProjectOptions): Promise<FlowSummary>;
+export {};

package/dist/flows/run/project.js

@@ -2,9 +2,15 @@ import path from "node:path";
 import { projectConfig } from "../../config/config.js";
 import { checkFlow, withKeys, } from "../core/index.js";
 import { DEFAULT_SRC_DIR, realPath, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
+import logger from "../../logger/index.js";
+import { resolveWorkers } from "../../runner/workers-option.js";
 import { withProject } from "../../runner/project.js";
+import { browsersFor } from "../../runner/browsers.js";
+import { DEFAULT_PORT } from "../../runner/ports.js";
 import { runTests } from "../../runner/run.js";
 import TestRunner from "../../runner/test-runner.js";
+import { WorkerPool } from "../../runner/worker-pool.js";
+import { processWorkerFactory } from "../../runner/worker-process.js";
 import { readFlow } from "./files.js";
 import { projectSteps } from "../steps/set.js";
 import { HANDLERS } from "./handlers/index.js";
@@ -17,16 +23,66 @@ export class FlowCheckError extends Error {
         this.name = "FlowCheckError";
     }
 }
+/** Whether the project's config defines an environment of this name */
+function hasEnvironment(config, name) {
+    return Object.prototype.hasOwnProperty.call(config.environments ?? {}, name);
+}
 /** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
 export function chooseEnvironment(config, flow, option) {
-    const names = Object.keys(config.environments ?? {});
     if (option)
         return option;
+    const names = Object.keys(config.environments ?? {});
     if (flow.envDefault && names.includes(flow.envDefault))
         return flow.envDefault;
     return config.defaultEnvironment ?? names[0] ?? "default";
 }
-/** What the project says about a flow: its environment, tests and groups */
+/** The work items of a node: each test in each browser, the browsers one after the other */
+function itemsOf(tests, browsers) {
+    return browsers
+        .flatMap((browser) => tests.map((t) => ({ file: t.file, testName: t.name, browser })))
+        .map((item, index) => ({ ...item, index }));
+}
+/** Runs the tests of a node on the pool and reports them as a run would */
+async function runOnPool(pool, items, onEvent, signal) {
+    const results = await pool.run(items, {
+        signal,
+        onEvent: (event) => onEvent({
+            type: event.type,
+            name: event.item.testName,
+            file: event.item.file,
+            browser: event.item.browser,
+            ...(event.type === "test-end" && { result: event.result }),
+        }),
+    });
+    if (signal.aborted)
+        return "cancelled";
+    return results.every((r) => r.status === "success") ? "passed" : "failed";
+}
+/** The tests, and the browsers, of each Test and Group node of a flow; a Test node uses the project's browsers */
+export function nodeTestsOf(flow, tests, groups) {
+    const byId = new Map(tests.map((t) => [t.id, t]));
+    const nodeTests = {};
+    const nodeBrowsers = {};
+    for (const node of flow.nodes) {
+        const group = node.kind === "group"
+            ? groups.find((g) => g.name === node.ref?.group)
+            : undefined;
+        const ids = node.kind === "test"
+            ? [node.ref?.testId ?? ""]
+            : node.kind === "group"
+                ? (group?.testIds ?? [])
+                : undefined;
+        if (!ids)
+            continue;
+        if (group)
+            nodeBrowsers[node.id] = group.browsers;
+        nodeTests[node.id] = ids.flatMap((id) => {
+            const t = byId.get(id);
+            return t ? [{ file: t.file, name: t.name }] : [];
+        });
+    }
+    return { nodeTests, nodeBrowsers };
+}
 async function prepare(options) {
     const projectDir = path.resolve(options.projectDir ?? process.cwd());
     if (!options.flow && !options.flowId)
@@ -40,7 +96,7 @@ async function prepare(options) {
     const environment = {
         name,
         variables: {
-            ...(Object.prototype.hasOwnProperty.call(config.environments ?? {}, name)
+            ...(hasEnvironment(config, name)
                 ? config.environments[name].variables
                 : {}),
         },
@@ -99,72 +155,98 @@ export async function checkFlowInProject(options) {
 /**
  * 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. One at a time per process.
+ * 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.
  */
 export async function runFlowInProject(options) {
     const { projectDir, flow, unsupported, config, steps, name, environment, tests, groups, problems, } = await prepare(options);
     const errors = problems.filter((p) => p.level === "error");
     if (errors.length)
         throw new FlowCheckError(errors);
-    // Phase 3: walk it
-    const byId = new Map(tests.map((t) => [t.id, t]));
-    const nodeTests = {};
-    const nodeBrowsers = {};
-    for (const node of flow.nodes) {
-        const ids = node.kind === "test"
-            ? [node.ref?.testId ?? ""]
-            : node.kind === "group"
-                ? (groups.find((g) => g.name === node.ref?.group)?.testIds ?? [])
-                : undefined;
-        if (!ids)
-            continue;
-        if (node.kind === "group") {
-            const browsers = groups.find((g) => g.name === node.ref?.group)?.browsers;
-            if (browsers)
-                nodeBrowsers[node.id] = browsers;
-        }
-        nodeTests[node.id] = ids.flatMap((id) => {
-            const t = byId.get(id);
-            return t ? [{ file: t.file, name: t.name }] : [];
+    const { nodeTests, nodeBrowsers } = nodeTestsOf(flow, tests, groups);
+    const run = options.testRunner ?? runTests;
+    // An injected runner (tests) stays in this process unless the workers are asked for
+    const asked = options.workers !== undefined ||
+        Boolean(options.workersEnv) ||
+        config.workers !== undefined;
+    let workers = options.testRunner && options.workers === undefined
+        ? 1
+        : resolveWorkers({
+            flag: options.workers,
+            env: options.workersEnv,
+            config: config.workers,
         });
+    // A worker reads `samurai.config.ts` from the project folder: a config given as an object stays in this process
+    if (options.config !== undefined && !options.createPool && workers > 1) {
+        if (asked)
+            logger.warn("workers needs samurai.config.ts in the project folder; running on one worker");
+        workers = 1;
     }
-    const run = options.testRunner ?? runTests;
-    return runFlow({
-        flow,
-        nodeTests,
-        nodeBrowsers,
-        environment,
-        ...(options.signal && { signal: options.signal }),
-        ...(options.onEvent && { onEvent: options.onEvent }),
-        ...(options.sleep && { sleep: options.sleep }),
-        unsupported,
-        handlers: { ...HANDLERS, ...steps.handlers },
-        nodes: steps.nodes,
-        runTests: async ({ tests, onEvent, signal, browsers }) => {
-            const summary = await run({
+    const files = [
+        ...new Set(Object.values(nodeTests).flatMap((list) => list.map((t) => t.file))),
+    ];
+    // One pool for the whole run: the nodes, and the branches of a Parallel node, share its workers
+    const pool = workers > 1
+        ? (options.createPool ?? ((o) => new WorkerPool(o)))({
+            workers,
+            factory: processWorkerFactory(),
+            init: {
                 projectDir,
-                config,
                 ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
-                // The environment the expressions see, whenever the project defines it
-                ...(Object.prototype.hasOwnProperty.call(config.environments ?? {}, name)
-                    ? { environment: name }
-                    : {}),
-                ...(options.headless !== undefined && { headless: options.headless }),
+                ...(hasEnvironment(config, name) && { environment: name }),
                 ...(options.timeout !== undefined && { timeout: options.timeout }),
                 ...(options.expectTimeout !== undefined && {
                     expectTimeout: options.expectTimeout,
                 }),
-                ...(options.port !== undefined && { port: options.port }),
-                ...(browsers && { browsers }),
-                files: [...new Set(tests.map((t) => t.file))],
-                testNames: tests.map((t) => t.name),
-                reportPath: false,
-                signal,
-                onEvent,
-            });
-            if (signal.aborted)
-                return "cancelled";
-            return summary.status === "success" ? "passed" : "failed";
-        },
-    });
+                ...(options.headless !== undefined && {
+                    headless: options.headless,
+                }),
+                files,
+                basePort: options.port ?? DEFAULT_PORT,
+            },
+        })
+        : undefined;
+    try {
+        return await runFlow({
+            flow,
+            nodeTests,
+            nodeBrowsers,
+            environment,
+            ...(options.signal && { signal: options.signal }),
+            ...(options.onEvent && { onEvent: options.onEvent }),
+            ...(options.sleep && { sleep: options.sleep }),
+            unsupported,
+            handlers: { ...HANDLERS, ...steps.handlers },
+            nodes: steps.nodes,
+            runTests: async ({ tests, onEvent, signal, browsers }) => {
+                if (pool)
+                    return runOnPool(pool, itemsOf(tests, browsers ?? browsersFor({ project: config.browsers })), onEvent, signal);
+                const summary = await run({
+                    projectDir,
+                    config,
+                    ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
+                    // The environment the expressions see, whenever the project defines it
+                    ...(hasEnvironment(config, name) ? { environment: name } : {}),
+                    ...(options.headless !== undefined && { headless: options.headless }),
+                    ...(options.timeout !== undefined && { timeout: options.timeout }),
+                    ...(options.expectTimeout !== undefined && {
+                        expectTimeout: options.expectTimeout,
+                    }),
+                    ...(options.port !== undefined && { port: options.port }),
+                    ...(browsers && { browsers }),
+                    files: [...new Set(tests.map((t) => t.file))],
+                    testNames: tests.map((t) => t.name),
+                    reportPath: false,
+                    signal,
+                    onEvent,
+                });
+                if (signal.aborted)
+                    return "cancelled";
+                return summary.status === "success" ? "passed" : "failed";
+            },
+        });
+    }
+    finally {
+        await pool?.dispose();
+    }
 }

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

@@ -39,9 +39,8 @@ export interface RunFlowOptions {
     nodes?: readonly AnyNodeDefinition[];
 }
 /**
- * Walks the flow from Start by the shape of each node's kind: a step runs and
- * follows its one way out; a node with a fixed list of branches follows the one its
- * handler names and skips the others; a node with a dynamic list walks every branch in
- * fill order; an end stops. Branches meet again at `meetOf`.
+ * Runs a flow: sets up what its nodes share (expression context, handler access to the tests), walks it from
+ * Start (see `FlowWalker`) and reports how it ended. A flow whose shape can't run ends with an `error`; a flow
+ * with a kind that has no handler throws before it starts, unless `unsupported` is `"skip"`.
  */
 export declare function runFlow(options: RunFlowOptions): Promise<FlowSummary>;