@itmetsam/samurai-framework 0.4.0 → 0.5.0

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

@@ -1,10 +1,12 @@
-import { type FlowFile } from "../flows/core/index.js";
+import { type AnyNodeDefinition, 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;
+    /** Definitions of the project's steps, for their labels. @default the built-in steps */
+    steps?: readonly AnyNodeDefinition[];
 }
 /** 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 {
@@ -12,8 +14,9 @@ export declare class FlowReporter {
     private readonly paint;
     private readonly nodes;
     private readonly flow;
+    private readonly steps;
     private started;
-    constructor({ flow, write, color }: FlowReporterOptions);
+    constructor({ flow, write, color, steps }: FlowReporterOptions);
     private shapeOf;
     private listed;
     private nameOf;

package/dist/cli/flow-reporter.js

@@ -5,8 +5,9 @@ const took = (ms) => ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(
 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 }) {
+    constructor({ flow, write, color, steps }) {
         this.started = Date.now();
+        this.steps = steps ?? STEP_NODES;
         this.flow = flow;
         this.write = write;
         this.paint = (code, text) => color ? `\u001b[${code}m${text}\u001b[0m` : text;
@@ -29,7 +30,7 @@ export class FlowReporter {
             label = nodeDef(node.kind).label;
         }
         catch {
-            label = STEP_NODES.find((d) => d.kind === node.kind)?.label ?? node.kind;
+            label = this.steps.find((d) => d.kind === node.kind)?.label ?? node.kind;
         }
         const base = node.title || label;
         const wrote = result.wrote ? Object.keys(result.wrote) : [];

package/dist/cli/flow.d.ts

@@ -1,4 +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";
+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 whose kind has no handler instead of refusing the flow (every built-in kind runs)\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

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { parseCommandLine, parseRunnerFlags, parseRunOverrides, } from "./args.js";
 import { FlowReporter } from "./flow-reporter.js";
+import { projectSteps } from "../flows/steps/index.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:
@@ -13,7 +14,7 @@ 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
+  --allow-unsupported         Skip nodes whose kind has no handler instead of refusing the flow (every built-in kind runs)
   --json                      Machine-readable output: JSON lines for run, one array for check and list
 
 Options for run:
@@ -136,6 +137,7 @@ async function run(refs, io, options) {
             io.err(`${flow.id} can't run:\n${problemLines(io, described)}Nothing was run.\n`);
         return 2;
     };
+    const { nodes: steps } = await projectSteps({ projectDir });
     // Several flows: refuse them all before the first one runs
     if (flows.length > 1) {
         for (const flow of flows) {
@@ -159,7 +161,7 @@ async function run(refs, io, options) {
         const builder = new FlowReportBuilder(flow);
         const human = options.json
             ? undefined
-            : new FlowReporter({ flow, write: io.out, color: io.color });
+            : new FlowReporter({ flow, write: io.out, color: io.color, steps });
         if (flows.indexOf(flow) > 0 && !options.json)
             io.out("\n");
         let summary;

package/dist/config/config.d.ts

@@ -19,6 +19,11 @@ export declare function projectDir(): string;
 export declare function browsersDir(): string;
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export declare function loadConfig(): Promise<SamuraiTestConfig>;
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export declare function projectConfig(options: {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<SamuraiTestConfig>;
 export declare function readConfig<K extends keyof SamuraiTestConfig>(key: K): Promise<SamuraiTestConfig[K]>;
 export declare function defineConfig(config: SamuraiTestConfig): SamuraiTestConfig;
 export {};

package/dist/config/config.js

@@ -32,6 +32,19 @@ export async function loadConfig() {
     }
     return config.default;
 }
+/** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
+export async function projectConfig(options) {
+    if (options.config)
+        return options.config;
+    const previous = activeProject;
+    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
+    try {
+        return await loadConfig();
+    }
+    finally {
+        setActiveProject(previous);
+    }
+}
 export async function readConfig(key) {
     const value = (await loadConfig())[key];
     logger.debug("Resolved config value: ", { value });

package/dist/flows/core/steps.js

@@ -1,7 +1,11 @@
 import { getPath } from "./nodes/path.js";
 export const STEP_KIND = /^[a-z][a-z0-9-]*$/;
 /** A node's own result fields: an output can't take these names */
-export const RESERVED_OUTPUTS = ["status", "durationMs", "error"];
+export const RESERVED_OUTPUTS = [
+    "status",
+    "durationMs",
+    "error",
+];
 const TITLE_FIELDS = [
     { path: "title", type: "text", label: "Title" },
     { path: "subtitle", type: "text", label: "Description" },
@@ -10,7 +14,11 @@ const empty = (value) => value === undefined || (typeof value === "string" && va
 /** Problems with `node`'s values against the fields' rules, as "Label: message" */
 export function fieldProblems(fields, node, label) {
     const problems = [];
-    const add = (message) => problems.push({ level: "error", nodeId: node.id, message: `${label}: ${message}` });
+    const add = (message) => problems.push({
+        level: "error",
+        nodeId: node.id,
+        message: `${label}: ${message}`,
+    });
     for (const f of fields) {
         const name = f.label ?? f.path;
         const value = getPath(node, f.path);
@@ -24,7 +32,10 @@ export function fieldProblems(fields, node, label) {
             if (f.max !== undefined && value > f.max)
                 add(`${name} must be at most ${f.max}.`);
         }
-        if (f.pattern && typeof value === "string" && value !== "" && !new RegExp(f.pattern).test(value))
+        if (f.pattern &&
+            typeof value === "string" &&
+            value !== "" &&
+            !new RegExp(f.pattern).test(value))
             add(f.patternMessage ?? `${name} doesn't match ${f.pattern}.`);
     }
     return problems;

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

@@ -5,4 +5,5 @@ export type { Handler, HandlerRun, Outcome } from "./handlers/index.js";
 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";

package/dist/flows/run/index.js

@@ -4,4 +4,5 @@ export { HANDLERS } from "./handlers/index.js";
 export { runFlow } from "./run.js";
 export { FLOW_SUFFIX, flowsDir, listFlows, readFlow, readFlowPath, readFlows, } from "./files.js";
 export * from "./report.js";
+export { projectSteps } from "../steps/set.js";
 export { FlowCheckError, checkFlowInProject, chooseEnvironment, runFlowInProject, } from "./project.js";

package/dist/flows/run/project.js

@@ -1,12 +1,12 @@
 import path from "node:path";
-import { loadConfig, setActiveProject } from "../../config/config.js";
+import { projectConfig } from "../../config/config.js";
 import { checkFlow, withKeys, } from "../core/index.js";
-import { DEFAULT_SRC_DIR, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
+import { DEFAULT_SRC_DIR, realPath, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
 import { withProject } from "../../runner/project.js";
 import { runTests } from "../../runner/run.js";
 import TestRunner from "../../runner/test-runner.js";
 import { readFlow } from "./files.js";
-import { STEP_NODES } from "../steps/catalog.js";
+import { projectSteps } from "../steps/set.js";
 import { HANDLERS } from "./handlers/index.js";
 import { runFlow } from "./run.js";
 /** The flow has errors; nothing was run */
@@ -17,18 +17,6 @@ export class FlowCheckError extends Error {
         this.name = "FlowCheckError";
     }
 }
-/** Reads the project's config without keeping the project active (`withProject` is one at a time) */
-async function configOf(options) {
-    if (options.config)
-        return options.config;
-    setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
-    try {
-        return await loadConfig();
-    }
-    finally {
-        setActiveProject(undefined);
-    }
-}
 /** 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 ?? {});
@@ -46,7 +34,8 @@ async function prepare(options) {
     const flow = withKeys(options.flow ?? (await readFlow(projectDir, options.flowId)));
     const unsupported = options.unsupported ?? "fail";
     // Config, environment, tests and groups (one project session, then it ends)
-    const config = await configOf({ ...options, projectDir });
+    const config = await projectConfig({ ...options, projectDir });
+    const steps = await projectSteps({ config });
     const name = chooseEnvironment(config, flow, options.environment);
     const environment = {
         name,
@@ -56,7 +45,9 @@ async function prepare(options) {
                 : {}),
         },
     };
-    const srcDir = path.resolve(projectDir, config.srcDir ?? DEFAULT_SRC_DIR);
+    // Real paths, like the registered test files
+    const realDir = realPath(projectDir);
+    const srcDir = realPath(path.resolve(realDir, config.srcDir ?? DEFAULT_SRC_DIR));
     const { tests, groups } = await withProject({
         projectDir,
         config,
@@ -70,22 +61,26 @@ async function prepare(options) {
             name: t.name,
             relative: toPosix(path.relative(srcDir, t.file)),
         }));
-        const groups = resolveGroups(config, tests.map((t) => ({ file: t.relative, name: t.name })), projectDir, srcDir);
+        const groups = resolveGroups(config, tests.map((t) => ({ file: t.relative, name: t.name })), realDir, srcDir);
         return { tests, groups };
     });
     const problems = checkFlow(flow, {
         tests: tests.map((t) => t.id),
         groups: groups.map((g) => g.name),
         environment,
-        handled: new Set(Object.keys(HANDLERS)),
+        handled: new Set([
+            ...Object.keys(HANDLERS),
+            ...Object.keys(steps.handlers),
+        ]),
         unsupported,
-        nodes: STEP_NODES,
+        nodes: steps.nodes,
     });
     return {
         projectDir,
         flow,
         unsupported,
         config,
+        steps,
         name,
         environment,
         tests,
@@ -107,7 +102,7 @@ export async function checkFlowInProject(options) {
  * its tests through `runTests`, one after the other. One at a time per process.
  */
 export async function runFlowInProject(options) {
-    const { projectDir, flow, unsupported, config, name, environment, tests, groups, problems, } = await prepare(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);
@@ -136,6 +131,8 @@ export async function runFlowInProject(options) {
         ...(options.onEvent && { onEvent: options.onEvent }),
         ...(options.sleep && { sleep: options.sleep }),
         unsupported,
+        handlers: { ...HANDLERS, ...steps.handlers },
+        nodes: steps.nodes,
         runTests: async ({ tests, onEvent, signal }) => {
             const summary = await run({
                 projectDir,

package/dist/flows/steps/api.js

@@ -1,5 +1,8 @@
 import { defineStep } from "./define.js";
-const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"].map((m) => ({ label: m, value: m }));
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"].map((m) => ({
+    label: m,
+    value: m,
+}));
 const isJson = (text) => {
     try {
         JSON.parse(text);
@@ -16,9 +19,27 @@ export const api = defineStep({
     icon: "globe",
     section: "integrations",
     fields: [
-        { path: "config.method", type: "select", label: "Method", options: METHODS, default: "GET" },
-        { path: "config.url", type: "expression", label: "URL", placeholder: 'env.baseUrl + "/health"', default: "" },
-        { path: "config.body", type: "code", label: "Body", placeholder: '{ "name": "test" }', default: "" },
+        {
+            path: "config.method",
+            type: "select",
+            label: "Method",
+            options: METHODS,
+            default: "GET",
+        },
+        {
+            path: "config.url",
+            type: "expression",
+            label: "URL",
+            placeholder: 'env.baseUrl + "/health"',
+            default: "",
+        },
+        {
+            path: "config.body",
+            type: "code",
+            label: "Body",
+            placeholder: '{ "name": "test" }',
+            default: "",
+        },
     ],
     summary: "{config.method} {config.url}",
     outputs: [
@@ -32,7 +53,9 @@ export const api = defineStep({
             signal,
             ...(body !== undefined && {
                 body,
-                headers: { "content-type": isJson(body) ? "application/json" : "text/plain" },
+                headers: {
+                    "content-type": isJson(body) ? "application/json" : "text/plain",
+                },
             }),
         });
         return { outputs: { statusCode: res.status, body: await res.text() } };

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

@@ -1,16 +1,22 @@
 import type { AnyNodeDefinition, FlowFile, FlowProblem, StepInfo } from "../core/index.js";
 import type { Handler } from "../run/handlers/support.js";
 import { type StepDefinition } from "./define.js";
+import type { SamuraiTestConfig } from "../../types/config.js";
 /** The built-in steps, in library order */
 export declare const STEPS: readonly StepDefinition<any>[];
 export declare const STEP_NODES: readonly AnyNodeDefinition[];
 export declare const STEP_HANDLERS: Readonly<Record<string, Handler>>;
 /** The steps as data, for the app */
 export declare const stepCatalog: (steps?: readonly StepDefinition<any>[]) => StepInfo[];
-/** The project's steps; the built-in ones for now (test-project steps come later) */
-export declare function listSteps(): Promise<StepInfo[]>;
-/** Only the steps' own `validate` problems: the app checks everything else itself */
+/** The project's steps as data: the built-ins, then its config's. `projectDir` defaults to the working directory. */
+export declare function listSteps(options?: {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<StepInfo[]>;
+/** Only the steps' own `validate` problems (the project's steps included): the app checks everything else itself */
 export declare function validateSteps(flow: FlowFile, options: {
     tests?: string[];
     groups?: string[];
-}): FlowProblem[];
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<FlowProblem[]>;

package/dist/flows/steps/catalog.js

@@ -1,29 +1,36 @@
-import { api } from "./api.js";
-import { infoOf, stepNode } from "./define.js";
-import { stepHandler } from "./handler.js";
-import { setVariable } from "./set-variable.js";
-import { wait } from "./wait.js";
+import { infoOf } from "./define.js";
+import { BUILTIN_SET, BUILTIN_STEPS, projectSteps } from "./set.js";
 /** The built-in steps, in library order */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const STEPS = [wait, setVariable, api];
-export const STEP_NODES = STEPS.map(stepNode);
-export const STEP_HANDLERS = Object.fromEntries(STEPS.map((s) => [s.kind, stepHandler(s)]));
+export const STEPS = BUILTIN_STEPS;
+export const STEP_NODES = BUILTIN_SET.nodes;
+export const STEP_HANDLERS = BUILTIN_SET.handlers;
 /** The steps as data, for the app */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const stepCatalog = (steps = STEPS) => steps.map(infoOf);
-/** The project's steps; the built-in ones for now (test-project steps come later) */
-export async function listSteps() {
-    return stepCatalog();
+/** The project's steps as data: the built-ins, then its config's. `projectDir` defaults to the working directory. */
+export async function listSteps(options = {}) {
+    return [...(await projectSteps(options)).catalog];
 }
-/** Only the steps' own `validate` problems: the app checks everything else itself */
-export function validateSteps(flow, options) {
+/** Only the steps' own `validate` problems (the project's steps included): the app checks everything else itself */
+export async function validateSteps(flow, options) {
+    const set = await projectSteps(options);
     const tests = options.tests ? new Set(options.tests) : undefined;
     const groups = options.groups ? new Set(options.groups) : undefined;
     return flow.nodes.flatMap((n) => {
-        const step = STEPS.find((s) => s.kind === n.kind);
+        const step = set.steps.find((s) => s.kind === n.kind);
         if (!step?.validate)
             return [];
-        const def = STEP_NODES.find((d) => d.kind === n.kind);
-        return step.validate({ ...n, config: { ...Object.fromEntries(step.fields.map((f) => [f.path.slice(7), "default" in f ? f.default : undefined])), ...n.config } }, { label: def.label, tests, groups });
+        const def = set.nodes.find((d) => d.kind === n.kind);
+        return step.validate({
+            ...n,
+            config: {
+                ...Object.fromEntries(step.fields.map((f) => [
+                    f.path.slice(7),
+                    "default" in f ? f.default : undefined,
+                ])),
+                ...n.config,
+            },
+        }, { label: def.label, tests, groups });
     });
 }

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

@@ -38,6 +38,8 @@ export interface StepDefinition<C = Record<string, unknown>> extends StepInfo {
     /** What the step does in a run: return to pass, throw to fail */
     run: (input: StepRunInput<C>) => Promise<StepResult | void>;
 }
+/** The checks every step passes: in `defineStep`, and again when a project lists it. Throws for a step that can't work. */
+export declare function checkStep(def: StepDefinition<any>, where?: string): void;
 /** Declares a flow step: one way in, one way out. Throws for a definition that can't work. */
 export declare function defineStep<const F extends readonly StepField[]>(def: Omit<StepDefinition<RunConfigOf<F>>, "fields"> & {
     fields: F;

package/dist/flows/steps/define.js

@@ -1,11 +1,14 @@
 import { CLOSED_KINDS, RESERVED_OUTPUTS, STEP_KIND, stepNodeOf, } from "../core/index.js";
-/** Declares a flow step: one way in, one way out. Throws for a definition that can't work. */
-export function defineStep(def) {
-    const name = `Step "${def.kind}"`;
+/** The checks every step passes: in `defineStep`, and again when a project lists it. Throws for a step that can't work. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function checkStep(def, where = "") {
+    const name = `Step "${def.kind}"${where}`;
     if (CLOSED_KINDS.includes(def.kind))
         throw new Error(`${name}: "${def.kind}" is a closed kind; steps can't replace it.`);
     if (!STEP_KIND.test(def.kind))
         throw new Error(`${name}: "${def.kind}" isn't a valid step kind. Use lowercase letters, digits and -.`);
+    if (!Array.isArray(def.fields))
+        throw new Error(`${name}: fields must be a list.`);
     for (const f of def.fields) {
         if (!f.path.startsWith("config."))
             throw new Error(`${name}: field "${f.path}" must be a config. path.`);
@@ -24,8 +27,16 @@ export function defineStep(def) {
         if (outputs.indexOf(o) !== outputs.lastIndexOf(o))
             throw new Error(`${name}: output "${o}" is declared twice.`);
     }
-    if (def.writesVar !== undefined && !def.fields.some((f) => f.path === def.writesVar))
+    if (def.writesVar !== undefined &&
+        !def.fields.some((f) => f.path === def.writesVar))
         throw new Error(`${name}: writesVar "${def.writesVar}" isn't one of its fields.`);
+    if (typeof def.run !== "function")
+        throw new Error(`${name}: run must be a function.`);
+}
+/** Declares a flow step: one way in, one way out. Throws for a definition that can't work. */
+export function defineStep(def) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    checkStep(def);
     return def;
 }
 /** The step as data, without its functions: what the catalog holds */

package/dist/flows/steps/handler.js

@@ -27,7 +27,9 @@ export function stepHandler(step) {
         const stopped = new Promise((resolve) => {
             if (run.signal.aborted)
                 resolve("stopped");
-            run.signal.addEventListener("abort", () => resolve("stopped"), { once: true });
+            run.signal.addEventListener("abort", () => resolve("stopped"), {
+                once: true,
+            });
         });
         let result;
         try {
@@ -36,7 +38,11 @@ export function stepHandler(step) {
                     config,
                     env: { ...run.context.env },
                     vars: { ...run.context.vars },
-                    node: { id: node.id, ...(node.key && { key: node.key }), ...(node.title && { title: node.title }) },
+                    node: {
+                        id: node.id,
+                        ...(node.key && { key: node.key }),
+                        ...(node.title && { title: node.title }),
+                    },
                     signal: run.signal,
                     sleep: (ms) => run.sleep(ms, run.signal),
                     log: (level, text) => run.log(node.id, level, text),
@@ -54,11 +60,17 @@ export function stepHandler(step) {
         const declared = new Set((step.outputs ?? []).map((o) => o.name));
         const extra = keysOf(result?.outputs).filter((k) => !declared.has(k));
         if (extra.length)
-            return { status: "failed", error: `${step.label} returned outputs it doesn't declare: ${extra.join(", ")}.` };
+            return {
+                status: "failed",
+                error: `${step.label} returned outputs it doesn't declare: ${extra.join(", ")}.`,
+            };
         const allowed = step.writesVar ? getPath(typed, step.writesVar) : undefined;
         const wrongVars = keysOf(result?.vars).filter((k) => k !== allowed);
         if (wrongVars.length)
-            return { status: "failed", error: `${step.label} wrote variables it doesn't declare: ${wrongVars.join(", ")}.` };
+            return {
+                status: "failed",
+                error: `${step.label} wrote variables it doesn't declare: ${wrongVars.join(", ")}.`,
+            };
         Object.assign(run.context.vars, result?.vars);
         return {
             status: "passed",

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

@@ -1,5 +1,6 @@
 /** Flow steps: define your own, and the built-in ones. Node only. */
-export { defineStep, stepNode, type RunConfigOf, type StepDefinition, type StepResult, type StepRunInput, } from "./define.js";
+export { checkStep, defineStep, stepNode, type RunConfigOf, type StepDefinition, type StepResult, type StepRunInput, } from "./define.js";
 export { stepHandler } from "./handler.js";
+export { BUILTIN_SET, BUILTIN_STEPS, projectSteps, stepSet, type StepSet, } from "./set.js";
 export { STEPS, STEP_HANDLERS, STEP_NODES, listSteps, stepCatalog, validateSteps, } from "./catalog.js";
-export type { StepField, StepInfo, StepOutput, StepSection } from "../core/index.js";
+export type { StepField, StepInfo, StepOutput, StepSection, } from "../core/index.js";

package/dist/flows/steps/index.js

@@ -1,4 +1,5 @@
 /** Flow steps: define your own, and the built-in ones. Node only. */
-export { defineStep, stepNode, } from "./define.js";
+export { checkStep, defineStep, stepNode, } from "./define.js";
 export { stepHandler } from "./handler.js";
+export { BUILTIN_SET, BUILTIN_STEPS, projectSteps, stepSet, } from "./set.js";
 export { STEPS, STEP_HANDLERS, STEP_NODES, listSteps, stepCatalog, validateSteps, } from "./catalog.js";

package/dist/flows/steps/set-variable.js

@@ -6,11 +6,22 @@ export const setVariable = defineStep({
     section: "control",
     fields: [
         {
-            path: "config.name", type: "text", label: "Name", placeholder: "orderId", default: "",
-            required: true, pattern: "^[a-z][a-z0-9_]*$",
+            path: "config.name",
+            type: "text",
+            label: "Name",
+            placeholder: "orderId",
+            default: "",
+            required: true,
+            pattern: "^[a-z][a-z0-9_]*$",
             patternMessage: "use lowercase letters, digits and _ for the name.",
         },
-        { path: "config.value", type: "expression", label: "Value", placeholder: '"order-" + run.environment', default: "" },
+        {
+            path: "config.value",
+            type: "expression",
+            label: "Value",
+            placeholder: '"order-" + run.environment',
+            default: "",
+        },
     ],
     summary: "vars.{config.name} = {config.value}",
     writesVar: "config.name",

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

@@ -0,0 +1,26 @@
+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 StepDefinition } from "./define.js";
+type AnyStep = StepDefinition<any>;
+/** The built-in steps, in library order */
+export declare const BUILTIN_STEPS: readonly AnyStep[];
+/** Everything a project's steps give the walker, the check and the app */
+export interface StepSet {
+    /** The built-ins, then the project's in config order */
+    steps: readonly AnyStep[];
+    nodes: readonly AnyNodeDefinition[];
+    handlers: Readonly<Record<string, Handler>>;
+    /** The steps as data, for the app */
+    catalog: StepInfo[];
+}
+/** The built-in steps plus a project's (its config's `steps`). Throws for a list that can't work. */
+export declare function stepSet(projectSteps?: unknown): StepSet;
+/** The built-in steps alone */
+export declare const BUILTIN_SET: StepSet;
+/** The project's steps: its config's `steps` after the built-ins. `projectDir` defaults to the working directory. */
+export declare function projectSteps(options?: {
+    projectDir?: string;
+    config?: SamuraiTestConfig;
+}): Promise<StepSet>;
+export {};

package/dist/flows/steps/set.js

@@ -0,0 +1,43 @@
+import { projectConfig } from "../../config/config.js";
+import { api } from "./api.js";
+import { checkStep, infoOf, stepNode } from "./define.js";
+import { stepHandler } from "./handler.js";
+import { setVariable } from "./set-variable.js";
+import { wait } from "./wait.js";
+/** The built-in steps, in library order */
+export const BUILTIN_STEPS = [wait, setVariable, api];
+const WHERE = " (samurai.config.ts)";
+/** The built-in steps plus a project's (its config's `steps`). Throws for a list that can't work. */
+export function stepSet(projectSteps = []) {
+    if (!Array.isArray(projectSteps))
+        throw new Error("samurai.config.ts: steps must be a list of steps.");
+    const builtin = new Set(BUILTIN_STEPS.map((s) => s.kind));
+    const seen = new Set();
+    projectSteps.forEach((entry, i) => {
+        const kind = entry && typeof entry === "object"
+            ? entry.kind
+            : undefined;
+        if (typeof kind !== "string" || kind === "")
+            throw new Error(`Step #${i + 1}${WHERE}: it has no kind; make it with defineStep.`);
+        checkStep(entry, WHERE);
+        if (builtin.has(kind))
+            throw new Error(`Step "${kind}"${WHERE}: a built-in step already uses this kind.`);
+        if (seen.has(kind))
+            throw new Error(`Step "${kind}"${WHERE}: declared twice.`);
+        seen.add(kind);
+    });
+    const steps = [...BUILTIN_STEPS, ...projectSteps];
+    return {
+        steps,
+        nodes: steps.map(stepNode),
+        handlers: Object.fromEntries(steps.map((s) => [s.kind, stepHandler(s)])),
+        catalog: steps.map(infoOf),
+    };
+}
+/** The built-in steps alone */
+export const BUILTIN_SET = stepSet();
+/** The project's steps: its config's `steps` after the built-ins. `projectDir` defaults to the working directory. */
+export async function projectSteps(options = {}) {
+    const config = await projectConfig(options);
+    return config.steps === undefined ? BUILTIN_SET : stepSet(config.steps);
+}

package/dist/flows/steps/wait.js

@@ -5,7 +5,14 @@ export const wait = defineStep({
     icon: "timer",
     section: "control",
     fields: [
-        { path: "config.ms", type: "number", label: "Duration", unit: "ms", default: 1000, min: 0 },
+        {
+            path: "config.ms",
+            type: "number",
+            label: "Duration",
+            unit: "ms",
+            default: 1000,
+            min: 0,
+        },
     ],
     summary: "{config.ms} ms",
     async run({ config, sleep }) {

package/dist/runner/groups.d.ts

@@ -23,6 +23,11 @@ export interface ResolvedGroup {
         title: string;
     }[];
 }
+/**
+ * The real path of `p` (symlinks resolved), or `p` itself when it does not exist. Registered test files come
+ * from stack traces, which resolve symlinks, so paths compared with them must be real too
+ */
+export declare function realPath(p: string): string;
 /** Separators of any platform become `/` */
 export declare const toPosix: (p: string) => string;
 /** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */

package/dist/runner/groups.js

@@ -1,8 +1,21 @@
+import { realpathSync } from "node:fs";
 import { matchesGlob, relative, resolve } from "node:path";
 /** The test folder when the config names none */
 export const DEFAULT_SRC_DIR = "./src";
 /** The spec pattern when a group names none */
 export const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/**
+ * The real path of `p` (symlinks resolved), or `p` itself when it does not exist. Registered test files come
+ * from stack traces, which resolve symlinks, so paths compared with them must be real too
+ */
+export function realPath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /** Separators of any platform become `/` */
 export const toPosix = (p) => p.replace(/\\/g, "/");
 /** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */

package/dist/runner/test-runner.js

@@ -14,7 +14,7 @@ import Page from "../browser/page.js";
 import { takePendingAssertions } from "../assert/expect.js";
 import { toTestError } from "./test-error.js";
 import { ConnectionClosedError } from "../transport/bidi-connection.js";
-import { DEFAULT_SRC_DIR, findGroup, resolveGroups, testId, toPosix, } from "./groups.js";
+import { DEFAULT_SRC_DIR, findGroup, realPath, resolveGroups, testId, toPosix, } from "./groups.js";
 import { judgePageLogs } from "./page-logs-report.js";
 /** Whether a test with this full name is selected by the options */
 export function isSelected(name, { grep, testNames }) {
@@ -81,8 +81,9 @@ export default class TestRunner {
     /** The config's groups, resolved against the tests the specs register */
     async resolveAll(tests) {
         const config = await loadConfig();
-        const dir = projectDir();
-        const srcDir = path.resolve(dir, config.srcDir ?? DEFAULT_SRC_DIR);
+        // Real paths: registered test files come from stack traces, which resolve symlinks
+        const dir = realPath(projectDir());
+        const srcDir = realPath(path.resolve(dir, config.srcDir ?? DEFAULT_SRC_DIR));
         const groups = resolveGroups(config, tests.map(({ file, name }) => ({
             file: toPosix(path.relative(srcDir, file)),
             name,

package/dist/types/config.d.ts

@@ -1,3 +1,4 @@
+import type { StepDefinition } from "../flows/steps/define.js";
 import type { SupportedBrowser } from "./browser.js";
 
 interface SamuraiTest {
@@ -57,6 +58,12 @@ export interface SamuraiTestConfig {
    * Define a group of test's you want to have executed with a certain configuration
    **/
   groups?: SamuraiGroup[];
+  /**
+   * Flow steps of this project, made with `defineStep`. Listed after the built-in steps;
+   * a kind a built-in or another step uses is refused.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  steps?: readonly StepDefinition<any>[];
   /**
    * The base URL to use when navigating the browser.
    * When recording starts, the browser will start at this URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {