@itmetsam/samurai-framework 0.20.0 → 0.21.1

package/README.md

@@ -149,6 +149,6 @@ The [documentation index](https://github.com/degrootsam/samurai-framework/wiki/H
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `bun run dev`          | `samurai` from the sources (`tsx src/index.ts`)                                                                     |
 | `bun run test`         | Unit tests of the framework (no browser needed)                                                                     |
-| `bun run test:browser` | Browser tests of the framework (Firefox; `SAMURAI_TEST_BROWSER=chrome` or `bun run test:browser:chrome` for Chrome) |
-| `bun run test:cli`     | Tests of the `samurai` command (build first)                                                                        |
+| `bun run test-browser` | Browser tests of the framework (Firefox; `SAMURAI_TEST_BROWSER=chrome` or `bun run test-browser-chrome` for Chrome) |
+| `bun run test-cli`     | Tests of the `samurai` command (build first)                                                                        |
 | `bun run build`        | Typechecks and compiles to `dist/`                                                                                  |

package/dist/api.d.ts

@@ -2,5 +2,5 @@ export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./r
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
-export type { AllHookFixtures, TestDetails, TestFixtures, } from "./types/test.js";
+export type { AllHookFixtures, TestDetails, TestFixtures, TestOptions, TestOutputs, } from "./types/test.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/assert/assertion-error.d.ts

@@ -13,11 +13,13 @@ export interface AssertionErrorDetails {
     actual: unknown;
     /** Description of the asserted locator, only for locator assertions */
     locator?: string | undefined;
+    /** The first line of the message, instead of `expect(<subject>).<matcher>` (for `outputs.save`) */
+    call?: string | undefined;
 }
 export declare class AssertionError extends Error {
     readonly matcher: string;
     readonly expected: unknown;
     readonly actual: unknown;
     readonly locator: string | undefined;
-    constructor({ matcher, expected, actual, locator }: AssertionErrorDetails);
+    constructor({ matcher, expected, actual, locator, call, }: AssertionErrorDetails);
 }

package/dist/assert/assertion-error.js

@@ -28,9 +28,9 @@ export function toReportValue(value) {
     }
 }
 export class AssertionError extends Error {
-    constructor({ matcher, expected, actual, locator }) {
+    constructor({ matcher, expected, actual, locator, call, }) {
         const subject = locator === undefined ? "value" : "locator";
-        const lines = [`expect(${subject}).${matcher}`];
+        const lines = [call ?? `expect(${subject}).${matcher}`];
         if (locator !== undefined) {
             lines.push(`  locator: ${locator}`);
         }

package/dist/assert/locator-assertions.d.ts

@@ -3,6 +3,32 @@ export interface LocatorAssertionOptions {
     /** Time (ms) to keep retrying. Defaults to config `expect.timeout`, then 5000 */
     timeout?: number;
 }
+/** The options of the checks that can keep the text they found */
+export interface TextAssertionOptions extends LocatorAssertionOptions {
+    /** Saves the text that passed (a RegExp's first group, else its match) as this output of the running test */
+    output?: string;
+}
+/** What `readEventually` reads, what it waits for and how its failure is named */
+export interface EventualRead<V> {
+    /** The matcher, with `not.` in front when negated */
+    name: string;
+    locator: Locator;
+    expected: unknown;
+    read: () => Promise<V>;
+    /** True for the read that ends the wait */
+    check: (actual: V) => boolean;
+    /** Time (ms) to keep retrying. Defaults to the expect timeout */
+    timeout?: number | undefined;
+    /** A read of `null` (no element) never passes, and fails as "could not read" */
+    mustExist?: boolean;
+    /** The first line of a failure, instead of `expect(locator).<name>` */
+    call?: string;
+}
+/**
+ * Re-reads the element until `check` passes or the timeout expires, and resolves with the read that passed. A
+ * timeout fails as an `AssertionError` with the last read, or as "could not read" when no read completed.
+ */
+export declare function readEventually<V>({ name, locator, expected, read, check, timeout: perCall, mustExist, call, }: EventualRead<V>): Promise<V>;
 export declare class LocatorAssertions {
     private readonly locator;
     private readonly negated;
@@ -14,15 +40,20 @@ export declare class LocatorAssertions {
      * (no element) never passes, with or without `.not`, and fails as "could not read"
      */
     private assertEventually;
+    /**
+     * A text check that can keep what it read: with `options.output` the read that passed goes to that output, as
+     * `expected` captures it. The sink is taken now, when the call starts.
+     */
+    private assertText;
     /** For matchers that need an element: `read` answers null when there is none, which never passes */
     private assertExisting;
     toBeVisible(options?: LocatorAssertionOptions): Promise<void>;
     /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
-    toHaveText(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    toHaveText(expected: string | RegExp, options?: TextAssertionOptions): Promise<void>;
     /** Text content contains `expected` (string) or matches it (RegExp) */
-    toContainText(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
-    toHaveValue(expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
-    toHaveAttribute(name: string, expected: string | RegExp, options?: LocatorAssertionOptions): Promise<void>;
+    toContainText(expected: string | RegExp, options?: TextAssertionOptions): Promise<void>;
+    toHaveValue(expected: string | RegExp, options?: TextAssertionOptions): Promise<void>;
+    toHaveAttribute(name: string, expected: string | RegExp, options?: TextAssertionOptions): Promise<void>;
     toHaveCount(expected: number, options?: LocatorAssertionOptions): Promise<void>;
     /** The element is missing, or has no box or is hidden by CSS (the opposite of `toBeVisible`) */
     toBeHidden(options?: LocatorAssertionOptions): Promise<void>;

package/dist/assert/locator-assertions.js

@@ -2,7 +2,33 @@ import { resolveTimeout } from "../config/timeouts.js";
 import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
 import { AssertionError } from "./assertion-error.js";
 import { track } from "./pending-assertions.js";
-import { classCheck, matchesText, textCheck } from "./text-match.js";
+import { bindOutput } from "../wait/output-sink.js";
+import { captured, classCheck, matchesText, textCheck } from "./text-match.js";
+/**
+ * Re-reads the element until `check` passes or the timeout expires, and resolves with the read that passed. A
+ * timeout fails as an `AssertionError` with the last read, or as "could not read" when no read completed.
+ */
+export async function readEventually({ name, locator, expected, read, check, timeout: perCall, mustExist = false, call, }) {
+    const timeout = await resolveTimeout(perCall);
+    try {
+        return await waitUntil(read, (actual) => (mustExist && actual === null ? false : check(actual)), { timeout });
+    }
+    catch (err) {
+        if (!(err instanceof WaitTimeoutError))
+            throw err;
+        // Reads never resolve to undefined, so an undefined `last` means no read completed
+        if (err.last === undefined || (mustExist && err.last === null)) {
+            throw new Error(`${call ?? `expect(locator).${name}`}: could not read ${locator.selector} within ${timeout}ms`);
+        }
+        throw new AssertionError({
+            matcher: name,
+            expected,
+            actual: err.last,
+            locator: locator.selector,
+            call,
+        });
+    }
+}
 export class LocatorAssertions {
     constructor(locator, negated = false) {
         this.locator = locator;
@@ -16,30 +42,32 @@ export class LocatorAssertions {
      * Re-reads the element until `check` passes or the timeout expires. With `mustExist`, a read of `null`
      * (no element) never passes, with or without `.not`, and fails as "could not read"
      */
-    assertEventually(matcher, expected, read, check, options, mustExist = false) {
+    assertEventually(matcher, expected, read, check, options, mustExist = false, save) {
         const name = this.negated ? `not.${matcher}` : matcher;
-        return track(name, (async () => {
-            const timeout = await resolveTimeout(options?.timeout);
-            try {
-                await waitUntil(read, (actual) => mustExist && actual === null
-                    ? false
-                    : check(actual) !== this.negated, { timeout });
-            }
-            catch (err) {
-                if (!(err instanceof WaitTimeoutError))
-                    throw err;
-                // Reads never resolve to undefined, so an undefined `last` means no read completed
-                if (err.last === undefined || (mustExist && err.last === null)) {
-                    throw new Error(`expect(locator).${name}: could not read ${this.locator.selector} within ${timeout}ms`);
-                }
-                throw new AssertionError({
-                    matcher: name,
-                    expected,
-                    actual: err.last,
-                    locator: this.locator.selector,
-                });
-            }
-        })());
+        return track(`expect(locator).${name}()`, readEventually({
+            name,
+            locator: this.locator,
+            expected,
+            read,
+            check: (actual) => check(actual) !== this.negated,
+            timeout: options?.timeout,
+            mustExist,
+        }).then((actual) => save?.(actual)));
+    }
+    /**
+     * A text check that can keep what it read: with `options.output` the read that passed goes to that output, as
+     * `expected` captures it. The sink is taken now, when the call starts.
+     */
+    assertText(matcher, expected, read, mode, options) {
+        let save;
+        if (options?.output !== undefined) {
+            const call = `expect(locator).${this.negated ? "not." : ""}${matcher}`;
+            if (this.negated)
+                throw new Error(`${call}: output can't be saved from a negated check`);
+            const keep = bindOutput(call, options.output);
+            save = (actual) => keep(captured(expected, actual));
+        }
+        return this.assertEventually(matcher, expected, read, textCheck(expected, mode), options, false, save);
     }
     /** For matchers that need an element: `read` answers null when there is none, which never passes */
     assertExisting(matcher, expected, read, check, options) {
@@ -50,17 +78,17 @@ export class LocatorAssertions {
     }
     /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
     toHaveText(expected, options) {
-        return this.assertEventually("toHaveText", expected, () => this.locator.textContent(), textCheck(expected, "exact"), options);
+        return this.assertText("toHaveText", expected, () => this.locator.textContent(), "exact", options);
     }
     /** Text content contains `expected` (string) or matches it (RegExp) */
     toContainText(expected, options) {
-        return this.assertEventually("toContainText", expected, () => this.locator.textContent(), textCheck(expected, "contains"), options);
+        return this.assertText("toContainText", expected, () => this.locator.textContent(), "contains", options);
     }
     toHaveValue(expected, options) {
-        return this.assertEventually("toHaveValue", expected, () => this.locator.inputValue(), textCheck(expected, "exact"), options);
+        return this.assertText("toHaveValue", expected, () => this.locator.inputValue(), "exact", options);
     }
     toHaveAttribute(name, expected, options) {
-        return this.assertEventually("toHaveAttribute", expected, () => this.locator.getAttribute(name), textCheck(expected, "exact"), options);
+        return this.assertText("toHaveAttribute", expected, () => this.locator.getAttribute(name), "exact", options);
     }
     toHaveCount(expected, options) {
         return this.assertEventually("toHaveCount", expected, () => this.locator.count(), (count) => count === expected, options);

package/dist/assert/page-assertions.js

@@ -19,7 +19,7 @@ export class PageAssertions {
      */
     assertEventually(matcher, what, expectedOf, read, check, options) {
         const name = this.negated ? `not.${matcher}` : matcher;
-        return track(name, (async () => {
+        return track(`expect(page).${name}()`, (async () => {
             // Resolved inside the tracked body: a throw (no base URL) rejects the tracked promise
             const expected = expectedOf();
             const timeout = await resolveTimeout(options?.timeout);

package/dist/assert/pending-assertions.d.ts

@@ -1,7 +1,8 @@
 /**
- * Returns the matcher names of locator assertions that were never awaited and are
+ * Returns the labels of locator assertions that were never awaited and are
  * still running or already failed, and stops tracking them. The runner calls this
  * after a test to detect a missing `await`.
  */
 export declare function takePendingAssertions(): string[];
-export declare function track(matcher: string, assertion: Promise<void>): Promise<void>;
+/** Tracks `assertion` until someone awaits it; `label` names the call when it never is */
+export declare function track(label: string, assertion: Promise<void>): Promise<void>;

package/dist/assert/pending-assertions.js

@@ -1,10 +1,10 @@
 /**
  * Locator assertions nobody has awaited yet that are still running or have failed,
- * mapped to their matcher name
+ * mapped to their label (the call as a message names it, e.g. `expect(locator).toBeVisible()`)
  */
 const pendingAssertions = new Map();
 /**
- * Returns the matcher names of locator assertions that were never awaited and are
+ * Returns the labels of locator assertions that were never awaited and are
  * still running or already failed, and stops tracking them. The runner calls this
  * after a test to detect a missing `await`.
  */
@@ -28,11 +28,12 @@ class TrackedAssertion extends Promise {
         return super.then(onfulfilled, onrejected);
     }
 }
-export function track(matcher, assertion) {
+/** Tracks `assertion` until someone awaits it; `label` names the call when it never is */
+export function track(label, assertion) {
     const tracked = new TrackedAssertion((resolve, reject) => {
         assertion.then(resolve, reject);
     });
-    pendingAssertions.set(tracked, matcher);
+    pendingAssertions.set(tracked, label);
     // The native then does not count as awaiting: a pass stops tracking, a failure stays
     // tracked. Handling the rejection keeps an un-awaited failure from being unhandled.
     Promise.prototype.then.call(tracked, () => pendingAssertions.delete(tracked), () => { });

package/dist/assert/text-match.d.ts

@@ -1,5 +1,11 @@
 /** Whether `actual` equals (`exact`) or contains (`contains`) `expected`, or matches it when it is a RegExp */
 export declare function matchesText(actual: string, expected: string | RegExp, mode: "exact" | "contains"): boolean;
+/**
+ * What a text check keeps as an output: the first capture group of a RegExp, else its whole match, else (a
+ * string, or no match) the whole `actual`. The flags `g` and `y` are dropped, so the result never depends on a
+ * `lastIndex` left by an earlier use.
+ */
+export declare function captured(matcher: string | RegExp, actual: string): string;
 /** A check for a read that may find nothing (`null`): true when the text is there and matches */
 export declare function textCheck(expected: string | RegExp, mode: "exact" | "contains"): (actual: string | null) => boolean;
 /** A check for a class attribute: a string equals it after collapsing whitespace and trimming both sides, a RegExp tests it as written */

package/dist/assert/text-match.js

@@ -5,6 +5,18 @@ export function matchesText(actual, expected, mode) {
         return actual.search(expected) !== -1;
     return mode === "exact" ? actual === expected : actual.includes(expected);
 }
+/**
+ * What a text check keeps as an output: the first capture group of a RegExp, else its whole match, else (a
+ * string, or no match) the whole `actual`. The flags `g` and `y` are dropped, so the result never depends on a
+ * `lastIndex` left by an earlier use.
+ */
+export function captured(matcher, actual) {
+    if (typeof matcher === "string")
+        return actual;
+    const plain = new RegExp(matcher.source, matcher.flags.replace(/[gy]/g, ""));
+    const match = plain.exec(actual);
+    return match ? (match[1] ?? match[0]) : actual;
+}
 /** A check for a read that may find nothing (`null`): true when the text is there and matches */
 export function textCheck(expected, mode) {
     return (actual) => actual !== null && matchesText(actual, expected, mode);

package/dist/browser/browser.js

@@ -67,12 +67,28 @@ export class Browser {
                 commandTimeout,
                 signal,
             });
+        // The launchers stop listening for the abort once the session is open. Until this returns, nobody else
+        // holds the browser to close it, so an abort still has to stop it here. Once: a second stop would cut
+        // Chrome's short (chromedriver killed while it still quits Chrome)
+        let abandoned = false;
+        const abandon = () => {
+            if (abandoned)
+                return;
+            abandoned = true;
+            abandonLaunch(proc, connector);
+        };
+        signal?.addEventListener("abort", abandon, { once: true });
         try {
-            return await Browser.attach(proc, connector, browserName);
+            const launched = await Browser.attach(proc, connector, browserName);
+            signal?.throwIfAborted();
+            return launched;
         }
         catch (err) {
-            abandonLaunch(proc, connector);
-            throw err;
+            abandon();
+            throw signal?.aborted ? signal.reason : err;
+        }
+        finally {
+            signal?.removeEventListener("abort", abandon);
         }
     }
     /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */

package/dist/browser/chrome-launch.d.ts

@@ -60,6 +60,8 @@ export declare class ChromeProcess extends EventEmitter implements BrowserProces
     private deleteSession;
     session: string | undefined;
     private done;
+    /** The session is being deleted: chromedriver is killed once that is over, not before */
+    private quitting;
     constructor(driver: Pick<ReturnType<typeof spawn>, "once" | "kill" | "exitCode" | "signalCode">, deleteSession?: (url: string) => Promise<unknown>);
     get exitCode(): number | null;
     get signalCode(): NodeJS.Signals | null;

package/dist/browser/chrome-launch.js

@@ -139,6 +139,8 @@ export class ChromeProcess extends EventEmitter {
         this.driver = driver;
         this.deleteSession = deleteSession;
         this.done = false;
+        /** The session is being deleted: chromedriver is killed once that is over, not before */
+        this.quitting = false;
         driver.once("exit", () => this.ended());
     }
     get exitCode() {
@@ -159,7 +161,10 @@ export class ChromeProcess extends EventEmitter {
         // Deleting the session makes chromedriver quit Chrome; killing chromedriver alone could leave it running
         const session = this.session;
         this.session = undefined;
+        if (this.quitting)
+            return true;
         if (session) {
+            this.quitting = true;
             this.deleteSession(session)
                 .catch(() => undefined)
                 .finally(() => this.driver.kill(signal));

package/dist/capabilities.d.ts

@@ -12,7 +12,7 @@ export declare const CAPABILITIES: {
     /** The recorder writing its recording to files in the project. */
     readonly recorderFiles: true;
     /** The flows contract version; a test keeps it equal to `FLOWS_API`. */
-    readonly flowsApi: 2;
+    readonly flowsApi: 3;
     /** Steps that flows can run, including project steps made with `defineStep`. */
     readonly flowSteps: true;
     /** Browsers the framework downloads and manages itself. */
@@ -31,14 +31,25 @@ export declare const CAPABILITIES: {
     readonly recorderStartStatus: true;
     /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
     readonly outputDir: true;
-    /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
-    readonly flowNodeFolders: true;
-    /** `nodeFolder(nodeId)` from `./flows/run`: a flow node's folder under `outputDir`, so an app need not rebuild it. */
-    readonly nodeFolder: true;
+    /**
+     * `runFlowInProject`'s `outputDir` gives each node its own folder. Version 2: one per browser run,
+     * `<browser>/nodes/<node id>/`, and screenshot paths in a node's results are relative to `outputDir`.
+     */
+    readonly flowNodeFolders: 2;
+    /** `nodeFolder(nodeId, browser)` from `./flows/run`: a flow node's folder under `outputDir` (version 2 takes the browser). */
+    readonly nodeFolder: 2;
     /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
     readonly assertionMatchers: 2;
     /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
     readonly pageAssertions: true;
+    /**
+     * Test inputs and outputs: `test()` options `{ inputs, outputs }`, the `inputs` / `outputs` fixtures, `{ output }` on
+     * `fill` and the text checks, `inputs` / `outputs` on results and `listTests`, the codec's `saveOutput` step and
+     * `declare` edit, and the recorder toolbar's Save as output and Insert → input.
+     */
+    readonly testInputsOutputs: true;
+    /** A flow runs once per browser: `browser` on every flow event, `flow-done`, `runFlowInProject` resolving to `FlowRunResult`. */
+    readonly flowPerBrowser: true;
 };
 /** The shape of {@link CAPABILITIES}. */
 export type Capabilities = typeof CAPABILITIES;

package/dist/capabilities.js

@@ -12,7 +12,7 @@ export const CAPABILITIES = {
     /** The recorder writing its recording to files in the project. */
     recorderFiles: true,
     /** The flows contract version; a test keeps it equal to `FLOWS_API`. */
-    flowsApi: 2,
+    flowsApi: 3,
     /** Steps that flows can run, including project steps made with `defineStep`. */
     flowSteps: true,
     /** Browsers the framework downloads and manages itself. */
@@ -31,12 +31,23 @@ export const CAPABILITIES = {
     recorderStartStatus: true,
     /** `outputDir` on `runTests` and `runFlowInProject`: a folder per run for the report and the screenshots. */
     outputDir: true,
-    /** `runFlowInProject`'s `outputDir` gives each node its own folder, `nodes/<node id>/`. */
-    flowNodeFolders: true,
-    /** `nodeFolder(nodeId)` from `./flows/run`: a flow node's folder under `outputDir`, so an app need not rebuild it. */
-    nodeFolder: true,
+    /**
+     * `runFlowInProject`'s `outputDir` gives each node its own folder. Version 2: one per browser run,
+     * `<browser>/nodes/<node id>/`, and screenshot paths in a node's results are relative to `outputDir`.
+     */
+    flowNodeFolders: 2,
+    /** `nodeFolder(nodeId, browser)` from `./flows/run`: a flow node's folder under `outputDir` (version 2 takes the browser). */
+    nodeFolder: 2,
     /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
     assertionMatchers: 2,
     /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
     pageAssertions: true,
+    /**
+     * Test inputs and outputs: `test()` options `{ inputs, outputs }`, the `inputs` / `outputs` fixtures, `{ output }` on
+     * `fill` and the text checks, `inputs` / `outputs` on results and `listTests`, the codec's `saveOutput` step and
+     * `declare` edit, and the recorder toolbar's Save as output and Insert → input.
+     */
+    testInputsOutputs: true,
+    /** A flow runs once per browser: `browser` on every flow event, `flow-done`, `runFlowInProject` resolving to `FlowRunResult`. */
+    flowPerBrowser: true,
 };

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

@@ -8,7 +8,7 @@ export interface FlowReporterOptions {
     /** 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. */
+/** Prints a flow run for a person, per browser: a header, one line per node as it ends, then a count. Start and End are not listed. */
 export declare class FlowReporter {
     private readonly write;
     private readonly paint;

package/dist/cli/flow-reporter.js

@@ -4,7 +4,7 @@ import { STEP_NODES } from "../flows/steps/index.js";
 import { painter } from "./paint.js";
 const took = (ms) => ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 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. */
+/** Prints a flow run for a person, per browser: a header, one line per node as it ends, then a count. Start and End are not listed. */
 export class FlowReporter {
     constructor({ flow, write, color, steps }) {
         this.started = Date.now();
@@ -42,7 +42,7 @@ export class FlowReporter {
     handle(event) {
         if (event.type === "flow-start") {
             this.started = Date.now();
-            this.write(`Flow "${this.flow.name}" against ${event.environment}\n`);
+            this.write(`Flow "${this.flow.name}" against ${event.environment} in ${event.browser}\n`);
         }
         else if (event.type === "node-end") {
             const node = this.nodes.get(event.nodeId);

package/dist/cli/flow.js

@@ -164,9 +164,9 @@ async function run(refs, io, options) {
             : new FlowReporter({ flow, write: io.out, color: io.color, steps });
         if (index > 0 && !options.json)
             io.out("\n");
-        let summary;
+        let result;
         try {
-            summary = await runFlowInProject({
+            result = await runFlowInProject({
                 ...options.run,
                 projectDir,
                 flow,
@@ -186,10 +186,10 @@ async function run(refs, io, options) {
                 return refuse(e.problems, flow);
             throw e;
         }
-        const file = await writeFlowReport(projectDir, builder.finish(summary));
+        const file = await writeFlowReport(projectDir, builder.finish(result));
         if (!options.json)
             io.out(`Report: ${path.relative(projectDir, file) || file}\n`);
-        if (summary.status !== "passed")
+        if (result.status !== "passed")
             code = 1;
     }
     return code;

package/dist/config/mask.d.ts

@@ -1,3 +1,4 @@
+import { type Logform } from "winston";
 export declare const MASK = "\u2022\u2022\u2022\u2022";
 /** Registers a secret value; every later maskText/maskDeep/log line hides it */
 export declare function registerSecret(name: string, value: string): void;
@@ -7,5 +8,8 @@ export declare function isShortSecret(value: string): boolean;
 export declare function maskText(text: string): string;
 /** A copy of `value` with every string in it masked, following JSON.stringify semantics for objects */
 export declare function maskDeep<T>(value: T): T;
-/** Winston format that masks every string field of a log entry (message and metadata) */
-export declare const maskFormat: import("logform").FormatWrap;
+/**
+ * Winston format that masks every string field of a log entry (message and metadata). Typed through winston's
+ * re-export: logform is winston's dependency, not ours, so an inferred type can't be named under an isolated install
+ */
+export declare const maskFormat: Logform.FormatWrap;

package/dist/config/mask.js

@@ -80,7 +80,10 @@ function walk(value, path) {
         path.delete(value);
     }
 }
-/** Winston format that masks every string field of a log entry (message and metadata) */
+/**
+ * Winston format that masks every string field of a log entry (message and metadata). Typed through winston's
+ * re-export: logform is winston's dependency, not ours, so an inferred type can't be named under an isolated install
+ */
 export const maskFormat = format((info) => {
     if (patterns.length === 0)
         return info;

package/dist/flows/core/check-io.d.ts

@@ -0,0 +1,23 @@
+import type { AnyNodeDefinition } from "./nodes/define.js";
+import type { FlowProblem } from "./nodes/index.js";
+import { type FlowFile, type FlowNodeModel } from "./schema.js";
+import { type FlowFacts } from "./wiring.js";
+/** What checkFlow hands the input and output checks */
+interface IoCheck {
+    facts: FlowFacts;
+    /** Expressions are checked only when the environment is known */
+    environment?: {
+        name: string;
+        variables: Record<string, unknown>;
+    };
+    nodes?: readonly AnyNodeDefinition[];
+    /** A node's name in messages */
+    titleOf: (node: FlowNodeModel) => string;
+}
+/**
+ * Problems with inputs and outputs: an input with no source, an override expression
+ * that doesn't check out, an entry for an input the test doesn't declare, a Group
+ * node with an expression, and two branches of one Parallel saving the same output.
+ */
+export declare function ioProblems(flow: FlowFile, check: IoCheck): FlowProblem[];
+export {};