@itmetsam/samurai-framework 0.9.0 → 0.12.0

package/dist/flows/run/run.js

@@ -1,55 +1,21 @@
-import { inFillOrder, meetOf, nodeDef, } from "../core/index.js";
+import {} from "../core/index.js";
 import logger from "../../logger/index.js";
 import { STEP_NODES } from "../steps/catalog.js";
 import { HANDLERS } from "./handlers/index.js";
-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 });
-});
-class ShapeError extends Error {
-}
-const dynamicBranches = (def) => def.shape === "branches" && !!def.branches && !Array.isArray(def.branches);
+import { assertRunnable, defaultSleep, definitionOf, ShapeError, shapeError, } from "./prepare-flow.js";
+import { FlowWalker } from "./walker.js";
 /**
- * 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 async function runFlow(options) {
     const { flow, onEvent = () => { } } = options;
     const signal = options.signal ?? new AbortController().signal;
     const handlers = options.handlers ?? HANDLERS;
     const nodes = options.nodes ?? STEP_NODES;
-    const defOf = (kind) => nodes.find((d) => d.kind === kind) ??
-        (() => {
-            try {
-                return nodeDef(kind);
-            }
-            catch {
-                return undefined;
-            }
-        })();
-    if ((options.unsupported ?? "fail") === "fail") {
-        const problems = flow.nodes
-            .map((n) => ({ n, def: defOf(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(" ")}`);
-    }
-    const byId = new Map(flow.nodes.map((n) => [n.id, n]));
-    const results = {};
+    if ((options.unsupported ?? "fail") === "fail")
+        assertRunnable(flow, nodes, handlers);
     const context = {
         env: { ...options.environment.variables },
         vars: {},
@@ -60,181 +26,51 @@ export async function runFlow(options) {
             startedAt: options.startedAt ?? new Date().toISOString(),
         },
     };
-    const handlerRun = {
+    const handlerRunFor = (context, signal) => ({
         flow,
         environment: options.environment,
         context,
         nodeTests: options.nodeTests,
+        ...(options.nodeBrowsers && { nodeBrowsers: options.nodeBrowsers }),
         signal,
         sleep: options.sleep ?? defaultSleep,
-        runTests: (tests, onTestEvent) => options.runTests({ tests, onEvent: onTestEvent, signal }),
+        runTests: (tests, onTestEvent, browsers) => options.runTests({
+            tests,
+            onEvent: onTestEvent,
+            signal,
+            ...(browsers && { browsers }),
+        }),
         onTestEvent: (nodeId, event) => onEvent({ type: "test", nodeId, event }),
         nodes,
         log: (nodeId, level, text) => logger[level](`[${nodeId}] ${text}`),
-    };
-    let stopped;
-    const visited = new Set();
-    const record = (node, result) => {
-        results[node.id] = result;
-        if (node.key)
-            context.nodes[node.key] = {
-                ...result.outputs,
-                status: result.status,
-                durationMs: result.durationMs,
-                error: result.error,
-            };
-    };
-    const out = (id) => flow.edges.filter((e) => e.source === id);
-    /** Marks every node from `from` up to `stop` as skipped (a branch not taken) */
-    const skip = (from, stop) => {
-        const seen = new Set();
-        const visit = (id) => {
-            if (id === stop || seen.has(id))
-                return;
-            seen.add(id);
-            const node = byId.get(id);
-            if (node && !results[id]) {
-                record(node, { status: "skipped" });
-                onEvent({
-                    type: "node-end",
-                    nodeId: id,
-                    result: { status: "skipped" },
-                });
-            }
-            for (const e of out(id))
-                visit(e.target);
-        };
-        visit(from);
-    };
-    const shapeError = (message) => new ShapeError(`This flow's shape can't run: ${message}`);
-    async function runNode(node, def) {
-        if (visited.has(node.id))
-            throw shapeError(`${node.key ?? node.id} is reached twice.`);
-        visited.add(node.id);
-        if (signal.aborted) {
-            stopped = "cancelled";
-            return undefined;
-        }
-        onEvent({ type: "node-start", nodeId: node.id });
-        const began = Date.now();
-        const handler = handlers[node.kind];
-        const outcome = handler
-            ? await handler(node, handlerRun)
-            : { status: "skipped", note: "Not supported yet" };
-        if (outcome === "cancelled" || signal.aborted) {
-            stopped = "cancelled";
-            return undefined;
-        }
-        const result = { ...outcome, durationMs: Date.now() - began };
-        record(node, result);
-        // A node with a dynamic list of branches ends after them: walk() reports it then
-        if (dynamicBranches(def))
-            return result;
-        onEvent({ type: "node-end", nodeId: node.id, result });
-        if (result.status === "failed" && node.onFailure === "stop")
-            stopped = "failed";
-        return result;
-    }
-    /** Whether `target` is on the chain from `from` before `stop` */
-    const reachesBefore = (from, target, stop) => {
-        const seen = new Set();
-        const visit = (id) => {
-            if (id === stop || seen.has(id))
-                return false;
-            if (id === target)
-                return true;
-            seen.add(id);
-            return out(id).some((e) => visit(e.target));
-        };
-        return visit(from);
-    };
-    /** Runs the chain from `from` up to `stop` (undefined: through End) */
-    async function walk(from, stop) {
-        let at = from;
-        while (at !== undefined && at !== stop && !stopped) {
-            const node = byId.get(at);
-            if (!node)
-                throw shapeError("an edge leads to a missing node.");
-            const def = defOf(node.kind);
-            if (!def)
-                throw shapeError(`${node.key ?? node.id} has an unknown kind (${node.kind}).`);
-            const result = await runNode(node, def);
-            if (!result || stopped)
-                return;
-            if (def.shape === "end")
-                return;
-            const edges = out(node.id);
-            if (def.shape === "branches") {
-                const meet = meetOf(flow, node.id);
-                if (!meet)
-                    throw shapeError(`the branches of ${node.key ?? node.id} never meet.`);
-                if (!dynamicBranches(def)) {
-                    const taken = result.status === "passed"
-                        ? edges.find((e) => e.sourceHandle === result.branch)
-                        : undefined;
-                    for (const e of edges)
-                        if (e !== taken)
-                            skip(e.target, meet);
-                    if (taken)
-                        await walk(taken.target, meet);
-                }
-                else {
-                    const opened = Date.now();
-                    for (const e of inFillOrder(edges)) {
-                        if (stopped)
-                            break;
-                        if (e.target !== meet)
-                            await walk(e.target, meet);
-                    }
-                    if (stopped === "cancelled") {
-                        // Stopped inside its branches: like any node cut short, it didn't run to the end
-                        delete results[node.id];
-                        return;
-                    }
-                    // The node fails when anything in its branches failed
-                    const failed = flow.nodes.some((n) => results[n.id]?.status === "failed" &&
-                        edges.some((e) => e.target !== meet && reachesBefore(e.target, n.id, meet)));
-                    const durationMs = (result.durationMs ?? 0) + Date.now() - opened;
-                    const ended = failed
-                        ? {
-                            ...result,
-                            durationMs,
-                            status: "failed",
-                            error: "A branch failed.",
-                        }
-                        : { ...result, durationMs };
-                    record(node, ended);
-                    onEvent({ type: "node-end", nodeId: node.id, result: ended });
-                    if (failed && node.onFailure === "stop")
-                        stopped = "failed";
-                    if (stopped)
-                        return;
-                }
-                at = meet;
-                continue;
-            }
-            if (edges.length !== 1)
-                throw shapeError(`${node.key ?? node.id} has ${edges.length} ways out.`);
-            at = edges[0].target;
-        }
-    }
+    });
+    const walker = new FlowWalker({
+        flow,
+        signal,
+        handlers,
+        nodes,
+        handlerRunFor,
+        context,
+        onEvent,
+    });
     onEvent({ type: "flow-start", environment: options.environment.name });
     let error;
-    const start = flow.nodes.find((n) => defOf(n.kind)?.shape === "start");
+    const start = flow.nodes.find((n) => definitionOf(nodes, n.kind)?.shape === "start");
     try {
         if (!start)
             throw shapeError("it has no Start.");
-        await walk(start.id);
+        await walker.walk(start.id);
     }
     catch (e) {
         if (!(e instanceof ShapeError))
             throw e;
         error = e.message;
     }
+    const results = walker.results;
     for (const node of flow.nodes)
         if (!results[node.id])
             results[node.id] = { status: "not-run" };
-    const status = stopped === "cancelled"
+    const status = walker.stopped === "cancelled"
         ? "cancelled"
         : error || Object.values(results).some((r) => r.status === "failed")
             ? "failed"

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

@@ -0,0 +1,56 @@
+import { type AnyNodeDefinition, type ExpressionContext, type FlowFile } from "../core/index.js";
+import { type Fork } from "./branch-context.js";
+import type { FlowEvent, NodeResult } from "./events.js";
+import type { Handler, HandlerRun } from "./handlers/index.js";
+/** What the walker needs of the run: the flow, who handles each kind, and where results and events go */
+export interface WalkerInput {
+    flow: FlowFile;
+    signal: AbortSignal;
+    handlers: Readonly<Record<string, Handler>>;
+    nodes: readonly AnyNodeDefinition[];
+    /** What the handlers get for a context and a signal; the walker also writes each result into `context.nodes` */
+    handlerRunFor: (context: ExpressionContext, signal: AbortSignal) => HandlerRun;
+    context: ExpressionContext;
+    onEvent: (event: FlowEvent) => void;
+}
+/**
+ * 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 at the same time, each with its own copy of the variables (see `BranchWalk`); an end
+ * stops. Branches meet again at `meetOf`.
+ */
+export declare class FlowWalker {
+    private readonly input;
+    /** Why the walk stopped early: a failed node that stops the flow, or an abort */
+    stopped: "failed" | "cancelled" | undefined;
+    /** The result of every node that ran or was skipped, by node id; shared with the walks of the branches */
+    readonly results: Record<string, NodeResult>;
+    /** Nodes already entered, so a node reached twice is a shape error; shared with the walks of the branches */
+    private readonly visited;
+    private readonly byId;
+    private readonly handlerRun;
+    constructor(input: WalkerInput, shared?: {
+        results: Record<string, NodeResult>;
+        visited: Set<string>;
+    });
+    /** The variables and node outputs this walk reads and writes */
+    get context(): ExpressionContext;
+    private definition;
+    private record;
+    private out;
+    /** Marks every node from `from` up to `stop` as skipped (a branch not taken) */
+    private skip;
+    private runNode;
+    /** Whether `target` is on the chain from `from` before `stop` */
+    private reachesBefore;
+    /**
+     * Walks the branches of a node with a dynamic list at the same time, then reports the node: failed when anything
+     * in them failed, or when two branches set a variable differently. A branch that fails and stops the flow cancels
+     * the others.
+     */
+    private walkBranches;
+    /** A walker for one branch: the same flow, results and visited nodes, but its own variables and its own signal */
+    forBranch(fork: Fork, signal: AbortSignal): FlowWalker;
+    /** Runs the chain from `from` up to `stop` (undefined: through End) */
+    walk(from: string, stop?: string): Promise<void>;
+}

package/dist/flows/run/walker.js

@@ -0,0 +1,225 @@
+import { inFillOrder, meetOf, } from "../core/index.js";
+import { forkContext, mergeForks } from "./branch-context.js";
+import { definitionOf, dynamicBranches, shapeError } from "./prepare-flow.js";
+/**
+ * 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 at the same time, each with its own copy of the variables (see `BranchWalk`); an end
+ * stops. Branches meet again at `meetOf`.
+ */
+export class FlowWalker {
+    constructor(input, shared = { results: {}, visited: new Set() }) {
+        this.input = input;
+        this.byId = new Map(input.flow.nodes.map((n) => [n.id, n]));
+        this.results = shared.results;
+        this.visited = shared.visited;
+        this.handlerRun = input.handlerRunFor(input.context, input.signal);
+    }
+    /** The variables and node outputs this walk reads and writes */
+    get context() {
+        return this.input.context;
+    }
+    definition(kind) {
+        return definitionOf(this.input.nodes, kind);
+    }
+    record(node, result) {
+        this.results[node.id] = result;
+        if (node.key)
+            this.input.context.nodes[node.key] = {
+                ...result.outputs,
+                status: result.status,
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+    }
+    out(id) {
+        return this.input.flow.edges.filter((e) => e.source === id);
+    }
+    /** Marks every node from `from` up to `stop` as skipped (a branch not taken) */
+    skip(from, stop) {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return;
+            seen.add(id);
+            const node = this.byId.get(id);
+            if (node && !this.results[id]) {
+                this.record(node, { status: "skipped" });
+                this.input.onEvent({
+                    type: "node-end",
+                    nodeId: id,
+                    result: { status: "skipped" },
+                });
+            }
+            for (const e of this.out(id))
+                visit(e.target);
+        };
+        visit(from);
+    }
+    async runNode(node, def) {
+        const { signal, handlers, onEvent } = this.input;
+        const { handlerRun } = this;
+        if (this.visited.has(node.id))
+            throw shapeError(`${node.key ?? node.id} is reached twice.`);
+        this.visited.add(node.id);
+        if (signal.aborted) {
+            this.stopped = "cancelled";
+            return undefined;
+        }
+        onEvent({ type: "node-start", nodeId: node.id });
+        const began = Date.now();
+        const handler = handlers[node.kind];
+        const outcome = handler
+            ? await handler(node, handlerRun)
+            : { status: "skipped", note: "Not supported yet" };
+        if (outcome === "cancelled" || signal.aborted) {
+            this.stopped = "cancelled";
+            return undefined;
+        }
+        const result = { ...outcome, durationMs: Date.now() - began };
+        this.record(node, result);
+        // A node with a dynamic list of branches ends after them: walk() reports it then
+        if (dynamicBranches(def))
+            return result;
+        onEvent({ type: "node-end", nodeId: node.id, result });
+        if (result.status === "failed" && node.onFailure === "stop")
+            this.stopped = "failed";
+        return result;
+    }
+    /** Whether `target` is on the chain from `from` before `stop` */
+    reachesBefore(from, target, stop) {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return false;
+            if (id === target)
+                return true;
+            seen.add(id);
+            return this.out(id).some((e) => visit(e.target));
+        };
+        return visit(from);
+    }
+    /**
+     * Walks the branches of a node with a dynamic list at the same time, then reports the node: failed when anything
+     * in them failed, or when two branches set a variable differently. A branch that fails and stops the flow cancels
+     * the others.
+     */
+    async walkBranches(node, result, meet) {
+        const { flow, onEvent } = this.input;
+        const edges = this.out(node.id);
+        const opened = Date.now();
+        const cancel = new AbortController();
+        const onAbort = () => cancel.abort();
+        if (this.input.signal.aborted)
+            onAbort();
+        else
+            this.input.signal.addEventListener("abort", onAbort, { once: true });
+        const walks = inFillOrder(edges)
+            .filter((e) => e.target !== meet)
+            .map((e) => new BranchWalk(this, e.target, meet, cancel));
+        const settled = await Promise.allSettled(walks.map((w) => w.done));
+        this.input.signal.removeEventListener("abort", onAbort);
+        const rejected = settled.find((r) => r.status === "rejected");
+        if (rejected)
+            throw rejected.reason;
+        if (walks.some((w) => w.stopped === "failed"))
+            this.stopped = "failed";
+        if (this.input.signal.aborted)
+            this.stopped = "cancelled";
+        if (this.stopped === "cancelled") {
+            // Stopped inside its branches: like any node cut short, it didn't run to the end
+            delete this.results[node.id];
+            return;
+        }
+        const { clash } = mergeForks(this.input.context, walks.map((w) => w.fork));
+        // The node fails when anything in its branches failed
+        const failed = flow.nodes.some((n) => this.results[n.id]?.status === "failed" &&
+            edges.some((e) => e.target !== meet && this.reachesBefore(e.target, n.id, meet)));
+        const durationMs = (result.durationMs ?? 0) + Date.now() - opened;
+        const ended = clash
+            ? {
+                ...result,
+                durationMs,
+                status: "failed",
+                error: `branches set ${clash} differently`,
+            }
+            : failed
+                ? {
+                    ...result,
+                    durationMs,
+                    status: "failed",
+                    error: "A branch failed.",
+                }
+                : { ...result, durationMs };
+        this.record(node, ended);
+        onEvent({ type: "node-end", nodeId: node.id, result: ended });
+        if (ended.status === "failed" && node.onFailure === "stop")
+            this.stopped = "failed";
+    }
+    /** A walker for one branch: the same flow, results and visited nodes, but its own variables and its own signal */
+    forBranch(fork, signal) {
+        return new FlowWalker({ ...this.input, context: fork.context, signal }, { results: this.results, visited: this.visited });
+    }
+    /** Runs the chain from `from` up to `stop` (undefined: through End) */
+    async walk(from, stop) {
+        const { flow } = this.input;
+        let at = from;
+        while (at !== undefined && at !== stop && !this.stopped) {
+            const node = this.byId.get(at);
+            if (!node)
+                throw shapeError("an edge leads to a missing node.");
+            const def = this.definition(node.kind);
+            if (!def)
+                throw shapeError(`${node.key ?? node.id} has an unknown kind (${node.kind}).`);
+            const result = await this.runNode(node, def);
+            if (!result || this.stopped)
+                return;
+            if (def.shape === "end")
+                return;
+            const edges = this.out(node.id);
+            if (def.shape === "branches") {
+                const meet = meetOf(flow, node.id);
+                if (!meet)
+                    throw shapeError(`the branches of ${node.key ?? node.id} never meet.`);
+                if (!dynamicBranches(def)) {
+                    const taken = result.status === "passed"
+                        ? edges.find((e) => e.sourceHandle === result.branch)
+                        : undefined;
+                    for (const e of edges)
+                        if (e !== taken)
+                            this.skip(e.target, meet);
+                    if (taken)
+                        await this.walk(taken.target, meet);
+                }
+                else {
+                    await this.walkBranches(node, result, meet);
+                    if (this.stopped)
+                        return;
+                }
+                at = meet;
+                continue;
+            }
+            if (edges.length !== 1)
+                throw shapeError(`${node.key ?? node.id} has ${edges.length} ways out.`);
+            at = edges[0].target;
+        }
+    }
+}
+/** One branch of a Parallel node, walking from its first node up to where the branches meet */
+class BranchWalk {
+    constructor(parent, from, meet, cancel) {
+        this.fork = forkContext(parent.context);
+        this.walker = parent.forBranch(this.fork, cancel.signal);
+        this.done = this.walker.walk(from, meet).then(() => {
+            // A failure that stops the flow cancels the branches still running
+            if (this.walker.stopped === "failed")
+                cancel.abort();
+        }, (error) => {
+            cancel.abort();
+            throw error;
+        });
+    }
+    get stopped() {
+        return this.walker.stopped;
+    }
+}

package/dist/flows/steps/catalog.d.ts

@@ -1,5 +1,5 @@
 import type { AnyNodeDefinition, FlowFile, FlowProblem, StepInfo } from "../core/index.js";
-import type { Handler } from "../run/handlers/support.js";
+import type { Handler } from "../run/handlers/types.js";
 import { type StepDefinition } from "./define.js";
 import type { SamuraiTestConfig } from "../../types/config.js";
 /** The built-in steps, in library order */

package/dist/flows/steps/handler.d.ts

@@ -1,4 +1,4 @@
-import { type Handler } from "../run/handlers/support.js";
+import type { Handler } from "../run/handlers/types.js";
 import { type StepDefinition } from "./define.js";
 /** The one handler every step runs through */
 export declare function stepHandler(step: StepDefinition<any>): Handler;

package/dist/flows/steps/set.d.ts

@@ -1,6 +1,6 @@
 import type { SamuraiTestConfig } from "../../types/config.js";
 import type { AnyNodeDefinition, StepInfo } from "../core/index.js";
-import type { Handler } from "../run/handlers/support.js";
+import type { Handler } from "../run/handlers/types.js";
 import { type StepDefinition } from "./define.js";
 type AnyStep = StepDefinition<any>;
 /** The built-in steps, in library order */

package/dist/index.js

@@ -1,5 +1,5 @@
 import { main } from "./cli/main.js";
-// Development entry (`bun run dev`): the same as `samurai run`, straight from the sources
+// Development entry (`npm run dev`, which runs `tsx src/index.ts`): the same as `samurai run`, straight from the sources
 const interrupt = new AbortController();
 process.on("SIGINT", () => {
     if (interrupt.signal.aborted)

package/dist/locator/actionability.d.ts

@@ -0,0 +1,33 @@
+import type { ElementHandle } from "../script/element-handle.js";
+import { type CheckName, type ElementState, type ProbeOptions, type WaitForState } from "./element-state.js";
+import { type HelperInstaller } from "./helper-realm.js";
+export interface ActionOptions {
+    /**
+     * Time (ms) to wait for the element to become actionable. Defaults to config `expect.timeout`, then 5000.
+     * 0 checks once without waiting; the stability check is skipped because it needs two probes
+     */
+    timeout?: number;
+    /** Skip every actionability check except "attached" */
+    force?: boolean;
+}
+/** What the actionability waits need of a locator: finding its element, calling into the page, naming itself */
+export interface ActionabilityContext {
+    resolveOne(): Promise<ElementHandle | null>;
+    call<T>(fn: string, args: unknown[], sandbox?: string): Promise<T>;
+    /** The locator's description for error messages */
+    readonly selector: string;
+    /** The page's helper realm; without it the probe source is sent on every poll */
+    readonly helpers: HelperInstaller | undefined;
+}
+/** Reads the element's actionability state: one search, one probe */
+export declare function probeState(ctx: ActionabilityContext, options: ProbeOptions): Promise<ElementState>;
+/**
+ * Probes until every required check passes and returns that state.
+ * Throws ActionTimeoutError describing the last probe on timeout.
+ */
+export declare function waitForActionable(ctx: ActionabilityContext, action: string, checks: readonly CheckName[], probe: ProbeOptions, options: ActionOptions | undefined): Promise<ElementState>;
+/** Waits until the element reaches `state` (default "visible"); does not scroll */
+export declare function waitForState(ctx: ActionabilityContext, { state, timeout }: {
+    state?: WaitForState;
+    timeout?: number;
+}): Promise<void>;