@itmetsam/samurai-framework 0.19.0 → 0.21.0

package/dist/recorder/toolbar/source/views-rail.js

@@ -1,7 +1,8 @@
 /** Views: the chip and the rail. A slice of the toolbar function: it shares one closure with its neighbours, see `../source.ts`. */
 export const VIEWS_RAIL_JS = String.raw `  // ---- Views ----
   const toolOn = (tool) =>
-    tool === "assert" ? ui.picking || ui.panel === "assert" : tool === "insert" ? ui.panel === "insert" || ui.panel === "new" : ui.panel === tool;
+    tool === "assert" || tool === "output" ? (ui.picking && ui.pickFor === tool) || ui.panel === tool
+      : tool === "insert" ? ui.panel === "insert" || ui.panel === "new" : ui.panel === tool;
 
   const chipView = () =>
     h("div", { class: "chip" },
@@ -30,7 +31,9 @@ export const VIEWS_RAIL_JS = String.raw `  // ---- Views ----
         ? h("button", { class: "b on", "data-action": "resume" }, ico("▶"), "Resume")
         : h("button", { class: "b", "data-action": "pause" }, ico("❚❚"), "Pause"),
       tool("assert", "✓", "Assert"),
-      ui.picking && h("div", { class: "note" }, "Click an element · Esc cancels"),
+      ui.picking && ui.pickFor === "assert" && h("div", { class: "note" }, "Click an element · Esc cancels"),
+      tool("output", "⇥", "Output"),
+      ui.picking && ui.pickFor === "output" && h("div", { class: "note" }, "Click an element · Esc cancels"),
       tool("page", "⌂", "Page"),
       tool("insert", "{x}", "Insert"),
       tool("wait", "⏱", "Wait"),

package/dist/recorder/toolbar/source.d.ts

@@ -9,22 +9,22 @@
  * `globalThis[Symbol.for("samurai.toolbar")]` in the sandbox holds the hook:
  * - `update(state)`: the recorder's state, after every change and every page load.
  * - `reply(id, result)`: the answer to `pick` (a `PickInfo`), to `page-info` (a `PageInfo`) or to `assert`,
- *   `assert-page`, `insert` and `add-insertable` (an `ActionReply`).
+ *   `assert-page`, `insert`, `add-insertable` and `save-output` (an `ActionReply`).
  * - `root`: the shadow root, for tests.
  * - `press(action, detail?)`: runs the handler a click on that control runs (for tests). Actions:
  *   `pause`, `resume`, `stop`, `collapse`, `expand`, `resume-yes`, `resume-no` (rail);
- *   `assert`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
+ *   `assert`, `output`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
  *   `pick { target }` (the element a picking click hit);
- *   `matcher { matcher }`, `not`, `assert-add` (Assert panel);
+ *   `matcher { matcher }`, `not`, `assert-add` (Assert panel); `output-save` (Save as output panel);
  *   `page-matcher { matcher }`, `page-not`, `page-add` (Page panel);
  *   `insert-item { kind, name }`, `insert-first`, `insert-new { kind }` (Insert list);
  *   `new-kind { kind }`, `new-save`, `new-cancel` (New variable or secret);
  *   `wait-add`, `screenshot-add`; `escape` (the Esc key); `dismiss { id }` (a warning's Dismiss button).
- *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `pageExpected`, `filter`,
+ *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `outputName`, `outputPattern`, `pageExpected`, `filter`,
  *   `name`, `value`, `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
  * - `rebind(send)`: used by a second run in the same document (a new recording), which keeps the host and
  *   swaps in that recording's toolbar channel.
- * - `state()`, `picking()`: the last state from `update` and whether the Assert picker is on (for tests).
+ * - `state()`, `picking()`: the last state from `update` and whether the Assert or Save as output picker is on (for tests).
  * - `dispose()`: removes the host and every listener the toolbar put on the window and document (the
  *   recording ended while the document stays open).
  *

package/dist/recorder/toolbar/source.js

@@ -24,22 +24,22 @@ import { ATTACH_JS } from "./source/attach.js";
  * `globalThis[Symbol.for("samurai.toolbar")]` in the sandbox holds the hook:
  * - `update(state)`: the recorder's state, after every change and every page load.
  * - `reply(id, result)`: the answer to `pick` (a `PickInfo`), to `page-info` (a `PageInfo`) or to `assert`,
- *   `assert-page`, `insert` and `add-insertable` (an `ActionReply`).
+ *   `assert-page`, `insert`, `add-insertable` and `save-output` (an `ActionReply`).
  * - `root`: the shadow root, for tests.
  * - `press(action, detail?)`: runs the handler a click on that control runs (for tests). Actions:
  *   `pause`, `resume`, `stop`, `collapse`, `expand`, `resume-yes`, `resume-no` (rail);
- *   `assert`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
+ *   `assert`, `output`, `page`, `insert`, `wait`, `screenshot` (open or close the tool);
  *   `pick { target }` (the element a picking click hit);
- *   `matcher { matcher }`, `not`, `assert-add` (Assert panel);
+ *   `matcher { matcher }`, `not`, `assert-add` (Assert panel); `output-save` (Save as output panel);
  *   `page-matcher { matcher }`, `page-not`, `page-add` (Page panel);
  *   `insert-item { kind, name }`, `insert-first`, `insert-new { kind }` (Insert list);
  *   `new-kind { kind }`, `new-save`, `new-cancel` (New variable or secret);
  *   `wait-add`, `screenshot-add`; `escape` (the Esc key); `dismiss { id }` (a warning's Dismiss button).
- *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `pageExpected`, `filter`,
+ *   Form inputs carry `data-field` (`expected`, `attribute`, `cssName`, `countIndex`, `outputName`, `outputPattern`, `pageExpected`, `filter`,
  *   `name`, `value`, `waitKind`, `seconds`, `shotName`, `fullPage`) and update on `input`/`change`.
  * - `rebind(send)`: used by a second run in the same document (a new recording), which keeps the host and
  *   swaps in that recording's toolbar channel.
- * - `state()`, `picking()`: the last state from `update` and whether the Assert picker is on (for tests).
+ * - `state()`, `picking()`: the last state from `update` and whether the Assert or Save as output picker is on (for tests).
  * - `dispose()`: removes the host and every listener the toolbar put on the window and document (the
  *   recording ended while the document stays open).
  *

package/dist/recorder/toolbar/types.d.ts

@@ -47,6 +47,8 @@ export interface ControllerOptions {
     /** Name → value; undefined when not set */
     secrets: Record<string, string | undefined>;
     secretsIgnored: boolean;
+    /** The test's declared inputs: name → default */
+    inputs?: Record<string, string>;
     /** Screenshot steps already in the test, for the default name */
     screenshots: number;
 }
@@ -56,20 +58,25 @@ export type Message = ToolbarMessage & {
 export type Of<A extends Message["action"]> = Extract<Message, {
     action: A;
 }>;
-/** The element picked for an Assert, and the locator behind each of its Count choices */
+/** The element picked for an Assert or Save as output, the locator behind each of its Count choices, and its text */
 export interface PickState {
     id: number;
     locator: LocatorSpec;
     counts: LocatorCall[];
+    /** Its text as `outputs.save` reads it, when it was picked, secrets included: it never goes back to the page */
+    text: string;
 }
-/** What the action handlers (assert, insert, add a variable or secret) use of the controller */
+/** The messages that expect a reply, and that a double click sends twice */
+export type Replying = Of<"assert" | "assert-page" | "insert" | "add-insertable" | "save-output">;
+/** What the action handlers (assert, insert, add a variable, secret or input, save as output) use of the controller */
 export interface ActionContext {
     readonly deps: ControllerDeps;
     readonly options: ControllerOptions;
     readonly variables: Map<string, string>;
     readonly secrets: Map<string, string | undefined>;
+    readonly inputs: Map<string, string>;
     isPaused(): boolean;
-    /** The picked element an `assert` with the same id refers to */
+    /** The picked element an `assert` or `save-output` with the same id refers to */
     pick(): PickState | undefined;
     setPick(pick: PickState | undefined): void;
     showToast(text: string): void;

package/dist/runner/options.d.ts

@@ -24,6 +24,11 @@ export interface RunnerOptions {
      * @default the config's `retries`, else 0
      */
     retries?: number | string;
+    /**
+     * Values for the inputs the tests declare, by name: every test of the run reads the names it declares from
+     * here, and its own default for a name missing here
+     */
+    inputs?: Record<string, string>;
     /** Run the browser without a window. @default false */
     headless?: boolean;
     /** Remote debugging port of the browser. @default DEFAULT_PORT (9223) */

package/dist/runner/pooled-run.d.ts

@@ -16,9 +16,10 @@ export interface PlannedTest {
 }
 /**
  * Lists the run: every selected test in the first browser, then every selected test in the next one. The
- * position in the list is the item's `index`. `serialKey` says which group makes a test run alone.
+ * position in the list is the item's `index`. `serialKey` says which group makes a test run alone. `inputs`, the
+ * run's input values, go with every item.
  */
-export declare function planItems(selected: RegisteredTestCase[], browsers: SupportedBrowser[], serialKey: (test: RegisteredTestCase) => string | undefined): {
+export declare function planItems(selected: RegisteredTestCase[], browsers: SupportedBrowser[], serialKey: (test: RegisteredTestCase) => string | undefined, inputs?: Record<string, string>): {
     items: WorkItem[];
     planned: PlannedTest[];
 };

package/dist/runner/pooled-run.js

@@ -2,9 +2,10 @@ import { idOf } from "./select.js";
 import { staticSkip } from "./skip.js";
 /**
  * Lists the run: every selected test in the first browser, then every selected test in the next one. The
- * position in the list is the item's `index`. `serialKey` says which group makes a test run alone.
+ * position in the list is the item's `index`. `serialKey` says which group makes a test run alone. `inputs`, the
+ * run's input values, go with every item.
  */
-export function planItems(selected, browsers, serialKey) {
+export function planItems(selected, browsers, serialKey, inputs) {
     const planned = browsers.flatMap((browser) => selected.map((test) => ({ test, browser })));
     // A test that does not run (skip, fixme) is in the plan but not in the queue; `index` is its place in the plan
     const items = planned.flatMap(({ test, browser }, index) => {
@@ -18,6 +19,7 @@ export function planItems(selected, browsers, serialKey) {
                 testName: test.name,
                 browser,
                 ...(key !== undefined && { serialKey: key }),
+                ...(inputs !== undefined && { inputs }),
             },
         ];
     });

package/dist/runner/registry.d.ts

@@ -1,14 +1,18 @@
-import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase, TestDetails } from "../types/test.js";
+import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase, TestDetails, TestOptions } from "../types/test.js";
 type Body = TestCaseBase["function"];
 /** `test(title, fn)`, `test.skip(title, fn)`, `test.skip(condition, reason)` and the other forms */
 export interface TestFunction {
     (title: string, fn: Body): void;
+    (title: string, options: TestOptions, fn: Body): void;
     /** Registers a test that is not run */
     skip: SkipFunction;
     /** Registers a test that is not run because it is known to be broken */
     fixme: SkipFunction;
     /** Runs only this test (and the other `only` ones) */
-    only(title: string, fn: Body): void;
+    only: {
+        (title: string, fn: Body): void;
+        (title: string, options: TestOptions, fn: Body): void;
+    };
 }
 /**
  * With a title and a body it registers a skipped test, `{ reason }` saying why; with a condition it skips the
@@ -16,7 +20,7 @@ export interface TestFunction {
  */
 interface SkipFunction {
     (title: string, fn: Body): void;
-    (title: string, details: TestDetails, fn: Body): void;
+    (title: string, options: TestOptions, fn: Body): void;
     (condition: boolean, reason?: string): void;
 }
 /** `describe.skip` and `describe.fixme`: every test inside gets the modifier, and `{ reason }` says why */

package/dist/runner/registry.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from "node:url";
 import logger from "../logger/index.js";
 import { SkipSignal } from "./skip.js";
+import { validateTestIO } from "./test-io.js";
 import { addHook, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 const registered = [];
 /** Runs `fn` as the `describe` block `title`, under `modifier` when there is one. `fn` runs immediately and must be synchronous. */
@@ -17,7 +18,8 @@ function openDescribe(file, title, fn, modifier, reason) {
         leaveSuite();
     }
 }
-function add(file, title, fn, modifier, reason) {
+function add(file, title, fn, modifier, extras = {}) {
+    const { reason, inputs, outputs } = extras;
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
@@ -28,6 +30,8 @@ function add(file, title, fn, modifier, reason) {
         file,
         suite,
         ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
+        ...(inputs && { inputs }),
+        ...(outputs && { outputs }),
     });
     logger.debug("Registered test %s", name);
 }
@@ -39,23 +43,37 @@ function titlesOf(suite) {
             titles.unshift(s.title);
     return titles;
 }
-/** The body and `{ reason }` of `(title, fn)` and `(title, details, fn)` */
-function bodyAndReason(call, title, second, third) {
-    const [details, fn] = typeof second === "function"
+/** The body and options of `(title, fn)` and `(title, options, fn)`; `describe` only reads `reason` from them */
+function bodyAndOptions(call, title, second, third) {
+    const [options, fn] = typeof second === "function"
         ? [undefined, second]
         : [second, third];
     if (typeof fn !== "function")
         throw new TypeError(`${call}(${JSON.stringify(title)}) needs a function as its last argument`);
-    const reason = details?.reason;
-    return { fn: fn, ...(reason !== undefined && { reason }) };
+    const reason = options?.reason;
+    return {
+        fn: fn,
+        ...(reason !== undefined && { reason }),
+        ...(options && call.startsWith("test") && validateTestIO(call, options)),
+    };
+}
+/** `test()` and `test.only()`: a reason only makes sense with skip and fixme */
+function registering(call, modifier) {
+    return ((title, second, third) => {
+        const { fn, reason, ...io } = bodyAndOptions(call, title, second, third);
+        if (reason !== undefined)
+            throw new Error(`${call}(): reason only applies to skip and fixme`);
+        // Frames: Error, callerFile, this function, the spec
+        add(callerFile(), title, fn, modifier, io);
+    });
 }
 /** `test.skip` and `test.fixme`: a title and a body register a test with the modifier; a condition skips the running test */
 function skipping(annotation) {
     return ((first, second, third) => {
         if (typeof first === "string") {
-            const { fn, reason } = bodyAndReason(`test.${annotation}`, first, second, third);
+            const { fn, ...extras } = bodyAndOptions(`test.${annotation}`, first, second, third);
             // Frames: Error, callerFile, this function, the spec
-            add(callerFile(), first, fn, annotation, reason);
+            add(callerFile(), first, fn, annotation, extras);
             return;
         }
         if (first)
@@ -65,14 +83,14 @@ function skipping(annotation) {
 /** `describe.skip` and `describe.fixme`, with or without `{ reason }` */
 function describeSkipping(annotation) {
     return ((title, second, third) => {
-        const { fn, reason } = bodyAndReason(`describe.${annotation}`, title, second, third);
+        const { fn, reason } = bodyAndOptions(`describe.${annotation}`, title, second, third);
         openDescribe(callerFile(), title, fn, annotation, reason);
     });
 }
-export const test = Object.assign((title, fn) => add(callerFile(), title, fn), {
+export const test = Object.assign(registering("test"), {
     skip: skipping("skip"),
     fixme: skipping("fixme"),
-    only: (title, fn) => add(callerFile(), title, fn, "only"),
+    only: registering("test.only", "only"),
 });
 export const describe = Object.assign((title, fn) => openDescribe(callerFile(), title, fn), {
     skip: describeSkipping("skip"),

package/dist/runner/reporter.d.ts

@@ -56,6 +56,10 @@ export interface TestEndExtras extends TestRetries {
         name: string;
         path: string;
     }[];
+    /** The test's inputs, when it declares any */
+    inputs?: Record<string, string>;
+    /** The test's saved outputs, when it declares any */
+    outputs?: Record<string, string>;
 }
 export default class TestReporter implements TestSink {
     private testResults;

package/dist/runner/reporter.js

@@ -146,6 +146,8 @@ export default class TestReporter {
             ...(extras?.logs && { logs: extras.logs }),
             ...(extras?.logsDropped && { logsDropped: extras.logsDropped }),
             ...(extras?.screenshots?.length && { screenshots: extras.screenshots }),
+            ...(extras?.inputs && { inputs: extras.inputs }),
+            ...(extras?.outputs && { outputs: extras.outputs }),
             ...(extras?.retry && { retry: extras.retry }),
             ...(extras?.flaky && { flaky: true }),
             ...(extras?.previousAttempts?.length && {

package/dist/runner/run-test.js

@@ -13,6 +13,8 @@ import { isSkipSignal, staticSkip } from "./skip.js";
 import { runOutput } from "./output.js";
 import { testDirOf } from "./test-dir.js";
 import { toTestError } from "./test-error.js";
+import { createInputsFixture, createOutputsFixture, ioOfAttempt, missingOutputs, } from "./test-io.js";
+import { beginOutputs, endOutputs } from "../wait/output-sink.js";
 /**
  * The state of one test run. A test ends once, whichever of finishing, failing, timing out, an abort or a
  * closed browser comes first: that one is reported and the rest are ignored.
@@ -28,6 +30,8 @@ class TestOutcome {
         this.closing = false;
         /** A person closed the browser, or it crashed, while the test ran */
         this.browserClosed = false;
+        /** The test's inputs and outputs, as its report entry lists them when it ends */
+        this.io = () => ({});
     }
     get isEnded() {
         return this.ended;
@@ -49,6 +53,7 @@ class TestOutcome {
         this.reporter.onTestEnd(this.test, this.browser, error, {
             ...logs,
             screenshots: this.evidence?.screenshots,
+            ...this.io(),
         });
     }
 }
@@ -137,6 +142,8 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
                 workerIndex: resources.workerIndex ?? 0,
                 env: createEnvFixture(settings.environment, settings.variables),
                 secrets: createSecretsFixture(settings.environment, secrets),
+                inputs: createInputsFixture(test.inputs, options.inputs),
+                outputs: createOutputsFixture(sink),
             };
             await runWithEachHooks(test.suite, fixtures, timeoutController.signal, () => test.function(fixtures));
             // Already reported as timed out
@@ -146,12 +153,18 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             if (unawaited.length > 0) {
                 outcome.finish({
                     message: unawaited
-                        .map((matcher) => `expect(locator).${matcher}() was not awaited`)
+                        .map((label) => `${label} was not awaited`)
                         .join("\n"),
                     type: "assertion",
                 }, await judgeLogs(page, true));
                 return;
             }
+            // Checked only after a pass: a test that failed first reports its own failure
+            const missing = missingOutputs(test.outputs, sink);
+            if (missing) {
+                outcome.finish(missing, await judgeLogs(page, true));
+                return;
+            }
             const verdict = await judgeLogs(page, false);
             outcome.finish(verdict.error, verdict);
         }
@@ -168,7 +181,15 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
                 : toTestError(err), await judgeLogs(page, true));
         }
     };
-    await Promise.race([limit, gone, runBody()]);
+    // Open for this attempt only: whatever a capture still saves after the attempt ended is ignored
+    const sink = beginOutputs(test.outputs ?? []);
+    outcome.io = () => ioOfAttempt(test, options.inputs, sink);
+    try {
+        await Promise.race([limit, gone, runBody()]);
+    }
+    finally {
+        endOutputs();
+    }
     clearTimeout(timeoutTimer);
     if (onRunAborted)
         options.signal?.removeEventListener("abort", onRunAborted);

package/dist/runner/run.d.ts

@@ -30,6 +30,13 @@ export interface FoundTest {
     modifier?: Modifier;
     /** The `{ reason }` given with the `skip` or `fixme` that applies */
     reason?: string;
+    /** The inputs the test declares, in declaration order, with their defaults; absent when it declares none */
+    inputs?: {
+        name: string;
+        default: string;
+    }[];
+    /** The names of the outputs the test declares; absent when it declares none */
+    outputs?: string[];
 }
 /**
  * Imports the project's specs without running anything and lists the tests the options select, each with the id

package/dist/runner/run.js

@@ -43,7 +43,7 @@ export async function listTests(options = {}) {
     return inProject(options, async (runner) => {
         const { tests, srcDir } = await runner.list();
         return tests.map((test) => {
-            const { name, file, modifier, reason } = test;
+            const { name, file, modifier, reason, inputs, outputs } = test;
             const relativeFile = toPosix(path.relative(srcDir, file));
             return {
                 id: testId(relativeFile, name),
@@ -52,6 +52,13 @@ export async function listTests(options = {}) {
                 relativeFile,
                 ...(modifier && { modifier }),
                 ...(reason !== undefined && { reason }),
+                ...(inputs && {
+                    inputs: Object.entries(inputs).map(([name, value]) => ({
+                        name,
+                        default: value,
+                    })),
+                }),
+                ...(outputs && { outputs }),
             };
         });
     });

package/dist/runner/test-io.d.ts

@@ -0,0 +1,30 @@
+import type { TestError, TestOptions, TestOutputs } from "../types/test.js";
+import type { OutputSink } from "../wait/output-sink.js";
+/**
+ * Checks the `inputs` and `outputs` of a `test()` options object and returns them, leaving out an empty or absent
+ * list. `call` is the form used (`test`, `test.only`, ...), named in the error.
+ */
+export declare function validateTestIO(call: string, options: TestOptions): {
+    inputs?: Record<string, string>;
+    outputs?: string[];
+};
+/**
+ * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
+ * name the test did not declare throws.
+ */
+export declare function createInputsFixture(declared: Record<string, string> | undefined, supplied: Record<string, string> | undefined): Readonly<Record<string, string>>;
+/**
+ * The `outputs` fixture of one attempt: `save` waits for the element's text (non-empty, or matching the pattern), as
+ * `toHaveText` reads it, and keeps it in `sink`. It keeps to its own attempt's sink, so a late value never lands in a later test.
+ */
+export declare function createOutputsFixture(sink: OutputSink): TestOutputs;
+/** The failure of a passing attempt that did not save every output it declared */
+export declare function missingOutputs(declared: readonly string[] | undefined, sink: OutputSink): TestError | undefined;
+/** What an attempt's result lists: its inputs when it declares any, its outputs so far when it declares any */
+export declare function ioOfAttempt(test: {
+    inputs?: Record<string, string>;
+    outputs?: string[];
+}, supplied: Record<string, string> | undefined, sink: OutputSink): {
+    inputs?: Record<string, string>;
+    outputs?: Record<string, string>;
+};

package/dist/runner/test-io.js

@@ -0,0 +1,111 @@
+import { captured, textCheck } from "../assert/text-match.js";
+import { readEventually } from "../assert/locator-assertions.js";
+import { track } from "../assert/pending-assertions.js";
+import { isPassthroughKey } from "../config/variables.js";
+import { isIoName } from "../flows/core/steps.js";
+function checkName(call, kind, name) {
+    if (typeof name !== "string" || !isIoName(name))
+        throw new Error(`${call}(): ${kind} ${quoted(name)} is not a valid name`);
+}
+const has = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+/** A name in a message: strings quoted, anything else as written */
+function quoted(name) {
+    return typeof name === "string" ? JSON.stringify(name) : String(name);
+}
+/**
+ * Checks the `inputs` and `outputs` of a `test()` options object and returns them, leaving out an empty or absent
+ * list. `call` is the form used (`test`, `test.only`, ...), named in the error.
+ */
+export function validateTestIO(call, options) {
+    const { inputs, outputs } = options;
+    const result = {};
+    if (inputs !== undefined) {
+        if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs))
+            throw new Error(`${call}(): inputs must be an object of names and defaults`);
+        for (const [name, value] of Object.entries(inputs)) {
+            checkName(call, "input", name);
+            if (typeof value !== "string")
+                throw new Error(`${call}(): input "${name}" needs a string default`);
+        }
+        if (Object.keys(inputs).length > 0)
+            result.inputs = { ...inputs };
+    }
+    if (outputs !== undefined) {
+        if (!Array.isArray(outputs))
+            throw new Error(`${call}(): outputs must be an array of names`);
+        const seen = new Set();
+        for (const name of outputs) {
+            checkName(call, "output", name);
+            if (seen.has(name))
+                throw new Error(`${call}(): output "${name}" is listed twice`);
+            seen.add(name);
+        }
+        if (outputs.length > 0)
+            result.outputs = [...outputs];
+    }
+    return result;
+}
+/**
+ * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
+ * name the test did not declare throws.
+ */
+export function createInputsFixture(declared, supplied) {
+    return new Proxy(Object.freeze(resolveInputs(declared, supplied)), {
+        get(target, key, receiver) {
+            if (isPassthroughKey(target, key) || has(target, key))
+                return Reflect.get(target, key, receiver);
+            throw new Error(`inputs.${String(key)}: not declared, add it to the test's inputs`);
+        },
+    });
+}
+/** Each declared input with the supplied value, else its default; names the test does not declare are left out */
+function resolveInputs(declared, supplied) {
+    return Object.fromEntries(Object.entries(declared ?? {}).map(([name, value]) => [
+        name,
+        supplied && has(supplied, name) ? supplied[name] : value,
+    ]));
+}
+/**
+ * The `outputs` fixture of one attempt: `save` waits for the element's text (non-empty, or matching the pattern), as
+ * `toHaveText` reads it, and keeps it in `sink`. It keeps to its own attempt's sink, so a late value never lands in a later test.
+ */
+export function createOutputsFixture(sink) {
+    return {
+        save: (name, locator, pattern) => track("outputs.save()", saveText(sink, name, locator, pattern)),
+    };
+}
+async function saveText(sink, name, locator, pattern) {
+    if (!sink.declares(name))
+        throw new Error(`outputs.save(): output ${JSON.stringify(name)} is not declared`);
+    const matches = pattern ? textCheck(pattern, "exact") : undefined;
+    const text = await readEventually({
+        name: "toHaveText",
+        locator,
+        expected: pattern ?? "an element with text",
+        read: () => locator.textContent(),
+        // Without a pattern, an element that has not rendered its value yet (no text) is waited for
+        check: (actual) => actual !== null && (matches ? matches(actual) : actual !== ""),
+        call: `outputs.save(${JSON.stringify(name)})`,
+    });
+    sink.set(name, pattern ? captured(pattern, text) : text);
+}
+/** The failure of a passing attempt that did not save every output it declared */
+export function missingOutputs(declared, sink) {
+    const saved = sink.values();
+    const missing = (declared ?? []).filter((name) => !has(saved, name));
+    if (missing.length === 0)
+        return undefined;
+    return {
+        message: missing
+            .map((name) => `output ${JSON.stringify(name)} was never saved`)
+            .join("\n"),
+        type: "assertion",
+    };
+}
+/** What an attempt's result lists: its inputs when it declares any, its outputs so far when it declares any */
+export function ioOfAttempt(test, supplied, sink) {
+    return {
+        ...(test.inputs && { inputs: resolveInputs(test.inputs, supplied) }),
+        ...(test.outputs && { outputs: sink.values() }),
+    };
+}

package/dist/runner/test-runner.js

@@ -88,7 +88,7 @@ export default class TestRunner {
             env: process.env.SAMURAI_RETRIES,
             config: config.retries,
         });
-        const plan = planItems(selected, browsers, serialKeyOf(loaded.groups, config.groups, loaded.srcDir));
+        const plan = planItems(selected, browsers, serialKeyOf(loaded.groups, config.groups, loaded.srcDir), this.options.inputs);
         // A pool larger than what can overlap would only hold idle workers: a group that runs one at a time needs one
         const lanes = concurrency(plan.items);
         const mode = poolMode({

package/dist/runner/worker-protocol.d.ts

@@ -13,6 +13,8 @@ export interface WorkItem {
     serialKey?: string;
     /** Where this test's screenshots go, instead of the run's `outputDir` (a flow gives each node its own) */
     outputDir?: string;
+    /** The values the run supplies for the inputs tests declare (`runTests({ inputs })`) */
+    inputs?: Record<string, string>;
 }
 /** What a worker needs to start: the project and the settings that are the same for every test */
 export interface WorkerInit {

package/dist/runner/worker-session.js

@@ -51,6 +51,7 @@ export function openSession(init) {
                         ...((perTest.outputDir ?? init.outputDir) !== undefined && {
                             outputDir: perTest.outputDir ?? init.outputDir,
                         }),
+                        ...(perTest.inputs !== undefined && { inputs: perTest.inputs }),
                         port,
                         signal,
                     };

package/dist/runner/worker.d.ts

@@ -8,6 +8,7 @@ export interface WorkerSession {
     /** Runs one test; `onEvent` gets the reporter's events for it. Aborting `signal` ends the test as aborted */
     runTest(test: RegisteredTestCase, browser: SupportedBrowser, signal: AbortSignal, onEvent: (event: RunEvent) => void, options?: {
         outputDir?: string;
+        inputs?: Record<string, string>;
     }): Promise<void>;
     /** Ends the project's session */
     close(): Promise<void>;

package/dist/runner/worker.js

@@ -54,7 +54,10 @@ export function handleMessages(channel, { open, exit }) {
                     id,
                     result: { ...event.result, worker: workerIndex },
                 });
-            }, item.outputDir !== undefined ? { outputDir: item.outputDir } : {});
+            }, {
+                ...(item.outputDir !== undefined && { outputDir: item.outputDir }),
+                ...(item.inputs !== undefined && { inputs: item.inputs }),
+            });
         }
         finally {
             current = undefined;

package/dist/steps/edit.d.ts

@@ -1,4 +1,4 @@
-import type { Step } from "./model.js";
+import type { Step, TestInput } from "./model.js";
 export type StepEdit = {
     op: "replace";
     test: number;
@@ -32,10 +32,21 @@ export type StepEdit = {
  | {
     op: "remove-test";
     test: number;
+}
+/**
+ * Sets the test's `inputs` and `outputs` in its options object: a given list replaces that list, one left out
+ * stays. When both end up empty the options object goes, unless it holds a `reason`
+ */
+ | {
+    op: "declare";
+    test: number;
+    inputs?: TestInput[];
+    outputs?: string[];
 };
 /**
  * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters
- * when the step reads a fixture (`env`, `secrets`) they don't have yet: everything else, formatting and
- * comments included, stays byte for byte.
+ * when the step reads a fixture (`env`, `secrets`, `inputs`, `outputs`) they don't have yet, and its `outputs`
+ * when the step saves one not declared yet: everything else, formatting and comments included, stays byte for
+ * byte. A step that reads an undeclared input is refused: `declare` it, with its default, first.
  */
 export declare function applyEdit(source: string, edit: StepEdit): string;