@itmetsam/samurai-framework 0.19.0 → 0.21.0

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

@@ -1,5 +1,5 @@
 import type { TestResult } from "../../types/test.js";
-import type { FlowEvent, FlowSummary, NodeResult } from "./events.js";
+import type { FlowBrowserRun, FlowEvent, FlowRunResult } from "./events.js";
 /** One test a Test or Group node ran, as the runner reported it */
 export type FlowTestResult = {
     nodeId: string;
@@ -9,14 +9,14 @@ export interface FlowReport {
     flow: string;
     name: string;
     environment: string;
-    status: FlowSummary["status"];
+    /** Across the browsers: see `FlowRunResult` */
+    status: FlowRunResult["status"];
     startedAt: string;
     durationMs: number;
-    nodes: Record<string, NodeResult>;
-    vars: Record<string, unknown>;
+    /** Every test of every run; each names its browser */
     tests: FlowTestResult[];
-    /** The flow couldn't be walked at all */
-    error?: string;
+    /** One entry per browser the flow ran in, in order: its nodes, variables and error */
+    runs: FlowBrowserRun[];
 }
 /** Follows a run's events and builds its report once it ends (or `finish` is given what is known) */
 export declare class FlowReportBuilder {
@@ -31,7 +31,7 @@ export declare class FlowReportBuilder {
     });
     handle(event: FlowEvent): void;
     private collect;
-    finish(summary: FlowSummary, environment?: string): FlowReport;
+    finish(result: FlowRunResult, environment?: string): FlowReport;
 }
 /** Writes `<projectDir>/result/flows/<id>.json` with the registered secrets masked, as `report.json` is. Returns the path */
 export declare function writeFlowReport(projectDir: string, report: FlowReport): Promise<string>;

package/dist/flows/run/report.js

@@ -20,18 +20,16 @@ export class FlowReportBuilder {
         if (event.type === "test-end")
             this.tests.push({ nodeId, ...event.result });
     }
-    finish(summary, environment = this.environment) {
+    finish(result, environment = this.environment) {
         return {
             flow: this.flow.id,
             name: this.flow.name,
             environment,
-            status: summary.status,
+            status: result.status,
             startedAt: this.startedAt,
             durationMs: Date.now() - this.started,
-            nodes: summary.nodes,
-            vars: summary.vars,
             tests: this.tests,
-            ...(summary.error ? { error: summary.error } : {}),
+            runs: result.runs,
         };
     }
 }

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

@@ -1,4 +1,4 @@
-import { type AnyNodeDefinition, type FlowFile } from "../core/index.js";
+import { type AnyNodeDefinition, type FlowFacts, type FlowFile } from "../core/index.js";
 import type { RunEvent } from "../../runner/reporter.js";
 import type { FlowEvent, FlowSummary, NodeTest } from "./events.js";
 import { type Handler } from "./handlers/index.js";
@@ -7,12 +7,23 @@ export interface RunFlowOptions {
     flow: FlowFile;
     /** The tests of each Test and Group node, by node id */
     nodeTests: Record<string, NodeTest[]>;
-    /** The browsers a Group node runs in (its group's); a node not listed uses the project's */
+    /** The browser of this walk: a flow runs once per browser, `runFlow` walks it once */
+    browser: SupportedBrowser;
+    /**
+     * The browsers each Test and Group node runs in. A listed node whose list lacks `browser` is skipped with the
+     * note `not run in <browser>`; a node not listed runs
+     */
     nodeBrowsers?: Record<string, SupportedBrowser[]>;
     environment: {
         name: string;
         variables: Record<string, string | number | boolean>;
     };
+    /**
+     * The project's tests' inputs and outputs and its groups' tests: with them, each Test and Group node's inputs are
+     * wired (`wiringAt`) and sent to its tests, and expressions can read a Test node's outputs. Without them no input
+     * is sent
+     */
+    facts?: FlowFacts;
     /** @default "manual" */
     trigger?: "manual";
     /** @default now */
@@ -25,8 +36,10 @@ export interface RunFlowOptions {
         tests: NodeTest[];
         onEvent: (e: RunEvent) => void;
         signal: AbortSignal;
-        /** Set for a node that runs in browsers of its own */
-        browsers?: SupportedBrowser[];
+        /** The run's browser */
+        browser: SupportedBrowser;
+        /** Values for the tests' inputs; absent when the node sends none */
+        inputs?: Record<string, string>;
     }) => Promise<"passed" | "failed" | "cancelled">;
     sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
     /**
@@ -41,8 +54,9 @@ export interface RunFlowOptions {
     nodes?: readonly AnyNodeDefinition[];
 }
 /**
- * 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"`.
+ * Runs a flow once, in `browser` (`runFlowInProject` runs it once per browser): sets up what its nodes share
+ * (expression context, handler access to the tests), walks it from Start (see `FlowWalker`) and reports how it
+ * ended. Every event carries `browser`. 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>;

package/dist/flows/run/run.js

@@ -5,12 +5,13 @@ import { HANDLERS } from "./handlers/index.js";
 import { assertRunnable, defaultSleep, definitionOf, ShapeError, shapeError, } from "./prepare-flow.js";
 import { FlowWalker } from "./walker.js";
 /**
- * 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"`.
+ * Runs a flow once, in `browser` (`runFlowInProject` runs it once per browser): sets up what its nodes share
+ * (expression context, handler access to the tests), walks it from Start (see `FlowWalker`) and reports how it
+ * ended. Every event carries `browser`. 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 { flow, browser, onEvent = () => { } } = options;
     const signal = options.signal ?? new AbortController().signal;
     const handlers = options.handlers ?? HANDLERS;
     const nodes = options.nodes ?? STEP_NODES;
@@ -26,22 +27,26 @@ export async function runFlow(options) {
             startedAt: options.startedAt ?? new Date().toISOString(),
         },
     };
-    const handlerRunFor = (context, signal) => ({
+    const handlerRunFor = (context, outputsById, signal) => ({
         flow,
         environment: options.environment,
         context,
+        outputsById,
+        ...(options.facts && { facts: options.facts }),
         nodeTests: options.nodeTests,
+        browser,
         ...(options.nodeBrowsers && { nodeBrowsers: options.nodeBrowsers }),
         signal,
         sleep: options.sleep ?? defaultSleep,
-        runTests: (nodeId, tests, onTestEvent, browsers) => options.runTests({
+        runTests: (nodeId, tests, onTestEvent, inputs) => options.runTests({
             nodeId,
             tests,
             onEvent: onTestEvent,
             signal,
-            ...(browsers && { browsers }),
+            browser,
+            ...(inputs && { inputs }),
         }),
-        onTestEvent: (nodeId, event) => onEvent({ type: "test", nodeId, event }),
+        onTestEvent: (nodeId, event) => onEvent({ type: "test", browser, nodeId, event }),
         nodes,
         log: (nodeId, level, text) => logger[level](`[${nodeId}] ${text}`),
     });
@@ -52,9 +57,14 @@ export async function runFlow(options) {
         nodes,
         handlerRunFor,
         context,
-        onEvent,
+        outputsById: {},
+        onEvent: (event) => onEvent({ ...event, browser }),
+    });
+    onEvent({
+        type: "flow-start",
+        browser,
+        environment: options.environment.name,
     });
-    onEvent({ type: "flow-start", environment: options.environment.name });
     let error;
     const start = flow.nodes.find((n) => definitionOf(nodes, n.kind)?.shape === "start");
     try {
@@ -82,6 +92,6 @@ export async function runFlow(options) {
         vars: context.vars,
         ...(error ? { error } : {}),
     };
-    onEvent({ type: "flow-end", summary });
+    onEvent({ type: "flow-end", browser, summary });
     return summary;
 }

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

@@ -1,17 +1,30 @@
 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 Fork, type OutputsById } from "./branch-context.js";
+import type { NodeResult } from "./events.js";
 import type { Handler, HandlerRun } from "./handlers/index.js";
+/** A node's event as the walker sends it; `runFlow` adds the run's browser */
+type NodeEvent = {
+    type: "node-start";
+    nodeId: string;
+} | {
+    type: "node-end";
+    nodeId: string;
+    result: NodeResult;
+};
 /** 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;
+    /**
+     * What the handlers get for a context, the outputs by node id and a signal; the walker also writes each result
+     * into `context.nodes` and its outputs into `outputsById`
+     */
+    handlerRunFor: (context: ExpressionContext, outputsById: OutputsById, signal: AbortSignal) => HandlerRun;
     context: ExpressionContext;
-    onEvent: (event: FlowEvent) => void;
+    outputsById: OutputsById;
+    onEvent: (event: NodeEvent) => 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
@@ -33,8 +46,10 @@ export declare class FlowWalker {
         results: Record<string, NodeResult>;
         visited: Set<string>;
     });
-    /** The variables and node outputs this walk reads and writes */
+    /** The variables and node outputs (by key) this walk reads and writes */
     get context(): ExpressionContext;
+    /** The node outputs by node id this walk reads and writes */
+    get outputsById(): OutputsById;
     private definition;
     private record;
     private out;
@@ -49,8 +64,9 @@ export declare class FlowWalker {
      * the others.
      */
     private walkBranches;
-    /** A walker for one branch: the same flow, results and visited nodes, but its own variables and its own signal */
+    /** A walker for one branch: the same flow, results and visited nodes, but its own variables, node outputs and 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>;
 }
+export {};

package/dist/flows/run/walker.js

@@ -1,5 +1,5 @@
 import { inFillOrder, meetOf, } from "../core/index.js";
-import { forkContext, mergeForks } from "./branch-context.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
@@ -13,17 +13,23 @@ export class FlowWalker {
         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);
+        this.handlerRun = input.handlerRunFor(input.context, input.outputsById, input.signal);
     }
-    /** The variables and node outputs this walk reads and writes */
+    /** The variables and node outputs (by key) this walk reads and writes */
     get context() {
         return this.input.context;
     }
+    /** The node outputs by node id this walk reads and writes */
+    get outputsById() {
+        return this.input.outputsById;
+    }
     definition(kind) {
         return definitionOf(this.input.nodes, kind);
     }
     record(node, result) {
         this.results[node.id] = result;
+        if (result.outputs)
+            this.input.outputsById[node.id] = result.outputs;
         if (node.key)
             this.input.context.nodes[node.key] = {
                 ...result.outputs,
@@ -131,7 +137,7 @@ export class FlowWalker {
             delete this.results[node.id];
             return;
         }
-        const { clash } = mergeForks(this.input.context, walks.map((w) => w.fork));
+        const { clash } = mergeForks(this.input.context, this.input.outputsById, 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)));
@@ -156,9 +162,14 @@ export class FlowWalker {
         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 */
+    /** A walker for one branch: the same flow, results and visited nodes, but its own variables, node outputs and signal */
     forBranch(fork, signal) {
-        return new FlowWalker({ ...this.input, context: fork.context, signal }, { results: this.results, visited: this.visited });
+        return new FlowWalker({
+            ...this.input,
+            context: fork.context,
+            outputsById: fork.outputsById,
+            signal,
+        }, { results: this.results, visited: this.visited });
     }
     /** Runs the chain from `from` up to `stop` (undefined: through End) */
     async walk(from, stop) {
@@ -208,7 +219,7 @@ export class FlowWalker {
 /** 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.fork = forkContext(parent.context, parent.outputsById);
         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

package/dist/locator/locator.d.ts

@@ -169,5 +169,7 @@ export default class Locator {
      */
     press(key: string, options?: ActionOptions): Promise<void>;
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
-    fill(value: string, options?: ActionOptions): Promise<void>;
+    fill(value: string, options?: ActionOptions & {
+        output?: string;
+    }): Promise<void>;
 }

package/dist/locator/locator.js

@@ -6,6 +6,7 @@ import { probeState, waitForActionable, waitForState, } from "./actionability.js
 import { ChainResolver } from "./chain-resolver.js";
 import { dropFiles, setInputFiles, } from "./file-actions.js";
 import { describeType, } from "./element-state.js";
+import { bindOutput } from "../wait/output-sink.js";
 import { cssPropertyName, IS_CHECKED_BODY } from "./element-reads.js";
 import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
 import { CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, ATTACHED_ONLY, } from "./page-scripts.js";
@@ -347,6 +348,10 @@ export default class Locator {
     }
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     async fill(value, options) {
+        // Taken when the call starts, so a fill that outlives its test saves into that test's closed sink
+        const save = options?.output === undefined
+            ? undefined
+            : bindOutput("fill()", options.output);
         const state = await this.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);
         // Typing over the selected existing value replaces it; Backspace clears it for an empty value
         const keys = value === "" ? NAMED_KEYS.Backspace : value;
@@ -355,6 +360,7 @@ export default class Locator {
         await this.wait();
         await this.callOnElement(undefined, `if (typeof el.select === "function") el.select();`);
         await typeText(this.biDiConnector, this.contextId, keys);
+        save?.(value);
     }
 }
 function booleanOrNull(value) {

package/dist/recorder/apply.js

@@ -1,12 +1,22 @@
 import { applyEdit } from "../steps/edit.js";
+import { parseSpec } from "../steps/parse.js";
 /** Writes a recorder event into the spec source, as an edit of test number `test` */
 export function applyRecorderEvent(source, test, event) {
-    return event.op === "remove"
-        ? applyEdit(source, { op: "remove", test, index: event.index })
-        : applyEdit(source, {
-            op: event.op,
+    if (event.op === "remove")
+        return applyEdit(source, { op: "remove", test, index: event.index });
+    const { declare } = event.op === "insert" ? event : {};
+    const inputs = parseSpec(source)[test]?.inputs ?? [];
+    const declared = declare && !inputs.some((input) => input.name === declare.name)
+        ? applyEdit(source, {
+            op: "declare",
             test,
-            index: event.index,
-            step: event.step,
-        });
+            inputs: [...inputs, declare],
+        })
+        : source;
+    return applyEdit(declared, {
+        op: event.op,
+        test,
+        index: event.index,
+        step: event.step,
+    });
 }

package/dist/recorder/normalise.d.ts

@@ -1,9 +1,12 @@
-import type { Expectation, FileEntry, LocatorSpec, PageExpectation, Step } from "../steps/model.js";
+import type { Expectation, FileEntry, LocatorSpec, PageExpectation, Step, TestInput } from "../steps/model.js";
 /** What the recorder does to the step list: a new step at `index`, a step rewritten in place, or one taken out */
-export type RecorderEvent = {
+export type RecorderEvent = 
+/** `declare`: an input the step reads, declared with its default before the step goes in */
+{
     op: "insert";
     index: number;
     step: Step;
+    declare?: TestInput;
 } | {
     op: "replace";
     index: number;
@@ -42,6 +45,16 @@ export type Observation = {
     not: boolean;
     expectation: Expectation;
 }
+/** The toolbar's Save as output: the element's text, or what `pattern` captures of it */
+ | {
+    type: "saveOutput";
+    locator: LocatorSpec;
+    name: string;
+    pattern?: {
+        source: string;
+        flags: string;
+    };
+}
 /** The toolbar's Page panel: the page's URL or title */
  | {
     type: "expectPage";
@@ -51,9 +64,11 @@ export type Observation = {
     type: "insert";
     locator: LocatorSpec;
     value: {
-        kind: "env" | "secret";
+        kind: "env" | "secret" | "input";
         name: string;
     };
+    /** A new input: its default */
+    declare?: string;
 }
 /** A file input got a click: the click recorded just before it opened the file picker */
  | {

package/dist/recorder/normalise.js

@@ -20,10 +20,15 @@ export class Normaliser {
     get nextIndex() {
         return this.next;
     }
-    insert(step) {
+    insert(step, declare) {
         this.lastStep = step;
         this.picker = undefined;
-        return { op: "insert", index: this.next++, step };
+        return {
+            op: "insert",
+            index: this.next++,
+            step,
+            ...(declare && { declare }),
+        };
     }
     /** The path (and query) of `url` when it is inside the base URL, else `url` */
     relative(url) {
@@ -47,6 +52,13 @@ export class Normaliser {
                     not: observation.not,
                     expectation: observation.expectation,
                 };
+            case "saveOutput":
+                return {
+                    kind: "saveOutput",
+                    name: observation.name,
+                    locator: observation.locator,
+                    ...(observation.pattern && { pattern: observation.pattern }),
+                };
             case "expectPage":
                 return {
                     kind: "expectPage",
@@ -79,7 +91,10 @@ export class Normaliser {
         const fromToolbar = this.toolbarStep(observation);
         if (fromToolbar) {
             this.lastFill = undefined;
-            return [this.insert(fromToolbar)];
+            const declare = observation.type === "insert" && observation.declare !== undefined
+                ? { name: observation.value.name, default: observation.declare }
+                : undefined;
+            return [this.insert(fromToolbar, declare)];
         }
         switch (observation.type) {
             case "picker":

package/dist/recorder/session-secrets.js

@@ -26,6 +26,10 @@ export async function toolbarOptions(run, source, dir, config, testIndex) {
         variables: run.settings.variables,
         secrets,
         secretsIgnored: await isGitIgnored(dir, `.env.${environment}`),
+        inputs: Object.fromEntries((tests[testIndex]?.inputs ?? []).map((input) => [
+            input.name,
+            input.default,
+        ])),
         screenshots: tests[testIndex]?.steps.filter(({ step }) => step.kind === "screenshot")
             .length ?? 0,
     };

package/dist/recorder/toolbar/action-guard.d.ts

@@ -1,13 +1,11 @@
 import type { ActionReply } from "./protocol.js";
-import type { Message, Of } from "./types.js";
-/** The messages that expect a reply, and that a double click sends twice */
-type Replying = Of<"assert" | "assert-page" | "insert" | "add-insertable">;
+import type { Message, Replying } from "./types.js";
 /**
  * Drops the repeat of an action that is running or was answered `{ ok: true }` (a double click: its first copy
  * answers), and lets a retry after `{ ok: false }` through.
  */
 export declare class ActionGuard {
-    /** Ids of `assert`, `assert-page`, `insert` and `add-insertable` being processed */
+    /** Ids of the replying actions (`REPLYING`) being processed */
     private readonly inFlight;
     /** Ids `accept` let through whose `run` hasn't started yet */
     private readonly claimed;
@@ -18,4 +16,3 @@ export declare class ActionGuard {
     /** Runs an action that expects a reply, unless it is a repeat (see `accept`); `reply` gets the answer */
     run(message: Replying, work: () => Promise<ActionReply>, reply: (id: number, result: ActionReply) => void): Promise<void>;
 }
-export {};

package/dist/recorder/toolbar/action-guard.js

@@ -1,10 +1,17 @@
+const REPLYING = [
+    "assert",
+    "assert-page",
+    "insert",
+    "add-insertable",
+    "save-output",
+];
 /**
  * Drops the repeat of an action that is running or was answered `{ ok: true }` (a double click: its first copy
  * answers), and lets a retry after `{ ok: false }` through.
  */
 export class ActionGuard {
     constructor() {
-        /** Ids of `assert`, `assert-page`, `insert` and `add-insertable` being processed */
+        /** Ids of the replying actions (`REPLYING`) being processed */
         this.inFlight = new Set();
         /** Ids `accept` let through whose `run` hasn't started yet */
         this.claimed = new Set();
@@ -13,10 +20,7 @@ export class ActionGuard {
     }
     /** Whether to process `message`; call it as the message arrives, before queueing it */
     accept(message) {
-        if (message.action !== "assert" &&
-            message.action !== "assert-page" &&
-            message.action !== "insert" &&
-            message.action !== "add-insertable")
+        if (!REPLYING.includes(message.action))
             return true;
         const { id } = message;
         if (this.inFlight.has(id) || this.done.has(id))

package/dist/recorder/toolbar/actions/insert.d.ts

@@ -1,6 +1,9 @@
 import type { ActionReply } from "../protocol.js";
 import type { ActionContext, Of } from "../types.js";
-/** Types a variable or secret the tester already has into the field they picked, and records one `insert` step */
+/** Types a variable, secret or input the tester already has into the field they picked, and records one `insert` step */
 export declare function insertAction(ctx: ActionContext, message: Of<"insert">): Promise<ActionReply>;
-/** Saves a new variable or secret to the project, then types it into the field and records the `insert` step */
+/**
+ * Adds a new variable, secret or input, then types it into the field and records the `insert` step. A variable or
+ * secret is saved to the project first; an input is declared by the step itself.
+ */
 export declare function addInsertableAction(ctx: ActionContext, message: Of<"add-insertable">): Promise<ActionReply>;

package/dist/recorder/toolbar/actions/insert.js

@@ -1,28 +1,39 @@
 import { ConfigEditError } from "../../../project/config-edit.js";
 import { SECRET_NAME } from "../../../project/secrets-file.js";
 import { ExistsError, VARIABLE_NAME } from "../../../project/variables.js";
-import { fail, NO_ENVIRONMENT, PAUSED, TYPE_FAILED, UNIDENTIFIABLE, } from "./reply.js";
-/** Types a variable or secret the tester already has into the field they picked, and records one `insert` step */
+import { fail, nameProblem, NO_ENVIRONMENT, PAUSED, TYPE_FAILED, UNIDENTIFIABLE, } from "./reply.js";
+/** Types a variable, secret or input the tester already has into the field they picked, and records one `insert` step */
 export async function insertAction(ctx, message) {
     if (ctx.isPaused())
         return fail(PAUSED);
     const { kind, name } = message;
-    const value = kind === "secret" ? ctx.secrets.get(name) : ctx.variables.get(name);
+    const value = kind === "secret"
+        ? ctx.secrets.get(name)
+        : kind === "input"
+            ? ctx.inputs.get(name)
+            : ctx.variables.get(name);
     if (value === undefined)
         return fail(kind === "secret"
             ? `Set a value for ${name} first`
-            : `There is no variable "${name}"`);
+            : kind === "input"
+                ? `There is no input "${name}"`
+                : `There is no variable "${name}"`);
     const locator = await locate(ctx, message);
     if (!locator)
         return fail(UNIDENTIFIABLE);
     return typeIn(ctx, locator, kind, name, value);
 }
-/** Saves a new variable or secret to the project, then types it into the field and records the `insert` step */
+/**
+ * Adds a new variable, secret or input, then types it into the field and records the `insert` step. A variable or
+ * secret is saved to the project first; an input is declared by the step itself.
+ */
 export async function addInsertableAction(ctx, message) {
     if (ctx.isPaused())
         return fail(PAUSED);
     const { kind, name } = message;
     const value = String(message.value ?? "");
+    if (kind === "input")
+        return addInput(ctx, message, name, value);
     if (kind === "env" && !ctx.options.canAddVariables)
         return fail(NO_ENVIRONMENT);
     const known = kind === "env"
@@ -56,6 +67,26 @@ export async function addInsertableAction(ctx, message) {
     ctx.push();
     return typeIn(ctx, locator, kind, name, value, true);
 }
+/**
+ * Types a new input's value and records the step with the declaration; the project is not written, the
+ * test's own `inputs` carries the default. The name counts as taken once the step is recorded.
+ */
+async function addInput(ctx, message, name, value) {
+    const problem = nameProblem(name);
+    if (problem)
+        return fail(problem, "name");
+    if (ctx.inputs.has(name))
+        return fail(`"${name}" already exists`, "name");
+    const locator = await locate(ctx, message);
+    if (!locator)
+        return fail(UNIDENTIFIABLE);
+    const reply = await typeIn(ctx, locator, "input", name, value, false, true);
+    if (reply.ok) {
+        ctx.inputs.set(name, value);
+        ctx.push();
+    }
+    return reply;
+}
 /** Undefined when `work` succeeded, else the reply for its error */
 async function write(work, replyFor) {
     try {
@@ -76,7 +107,7 @@ async function locate(ctx, message) {
         return undefined; // the element went away
     }
 }
-async function typeIn(ctx, locator, kind, name, value, saved = false) {
+async function typeIn(ctx, locator, kind, name, value, saved = false, declare = false) {
     try {
         await ctx.deps.type(locator, value);
     }
@@ -86,7 +117,12 @@ async function typeIn(ctx, locator, kind, name, value, saved = false) {
         ctx.push();
         return fail(TYPE_FAILED);
     }
-    ctx.deps.observe({ type: "insert", locator, value: { kind, name } });
+    ctx.deps.observe({
+        type: "insert",
+        locator,
+        value: { kind, name },
+        ...(declare && { declare: value }),
+    });
     return { ok: true };
 }
 const errorText = (err) => err instanceof Error ? err.message : String(err);