@itmetsam/samurai-framework 0.21.0 → 0.21.2

package/README.md

@@ -2,7 +2,9 @@
 
 A browser test framework written in TypeScript. It drives a real browser over the [WebDriver BiDi](https://www.w3.org/TR/webdriver-bidi/) protocol, with no Playwright or Puppeteer underneath. Firefox speaks BiDi itself; Chrome is driven through its own `chromedriver`, which the framework starts for you.
 
-[![CI](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@itmetsam/samurai-framework)](https://www.npmjs.com/package/@itmetsam/samurai-framework)
+
+> This repository is a read-only mirror of `packages/framework` in the SAMURAI monorepo. Issues are welcome; pull requests aren't merged here. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ```ts
 import { expect, test } from "../api.js";
@@ -56,6 +58,8 @@ cd samurai-framework
 bun install
 ```
 
+The clone is the mirror described in [CONTRIBUTING.md](CONTRIBUTING.md). It has no lockfile of its own (the monorepo keeps one for all its packages), so `bun install` resolves the ranges in `package.json`.
+
 ### 3. Write a test
 
 Tests live in the folder `srcDir` points to (`./src/tests` in `samurai.config.ts`) and end in `.spec.ts`. This repository has one as `src/tests/example.spec.ts`:
@@ -138,7 +142,8 @@ Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win ove
 | [Running tests and reports](https://github.com/degrootsam/samurai-framework/wiki/Running-tests-and-reports) | What a run does, `report.json`, page logs, timeouts                                                   |
 | [Steps and the recorder](https://github.com/degrootsam/samurai-framework/wiki/Steps-and-the-recorder)       | The step codec, the recording engine and the recorder toolbar                                         |
 | [Embedding the framework](https://github.com/degrootsam/samurai-framework/wiki/Embedding-the-framework)     | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
-| [Contributing](docs/contributing.md)                                                                        | Project layout, running the framework's own tests, conventions                                        |
+| [Contributing](CONTRIBUTING.md)                                                                             | Issues and pull requests on this mirror                                                               |
+| [Developer guide](docs/contributing.md)                                                                     | Project layout, running the framework's own tests, conventions                                        |
 | [Roadmap](https://github.com/degrootsam/samurai-framework/wiki/Roadmap)                                     | What is built and what is still open                                                                  |
 
 The [documentation index](https://github.com/degrootsam/samurai-framework/wiki/Home) lists every guide by topic.
@@ -149,6 +154,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/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/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/network/network-tracker.d.ts

@@ -11,6 +11,12 @@ export interface TrackerOptions {
  * Follows the network activity of one page (its frames included): which requests are in flight,
  * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
  * so a redirect chain is one live request at a time.
+ *
+ * Chrome (chromium-bidi) reports a redirect response only once the browser has started the next hop, and it can
+ * leave out that hop's `beforeRequestSent`: when the hop's `requestWillBeSentExtraInfo` reaches it before the
+ * redirect's `requestWillBeSent`, it files the extra info under the previous hop and never announces the new one.
+ * So on Chrome a redirect keeps the chain in flight until the next hop shows itself, and a hop that first shows up
+ * with its response or error is announced then.
  */
 export declare class NetworkTracker {
     private tree;
@@ -21,13 +27,16 @@ export declare class NetworkTracker {
     private subscription;
     /**
      * Every hop that is in flight or may still be the source of a redirect, by hop key. A redirect response ends a
-     * hop's flight (`live` false) but keeps it, for the next hop's `redirectedFrom`.
+     * hop's flight (`live` false; on Chrome `answered`, live until the next hop shows) but keeps it, for the next
+     * hop's `redirectedFrom`.
      */
     private hops;
     /** Rejects a pending `waitForIdle`; each wait adds its own */
     private waiters;
     private disposed;
     private constructor();
+    /** Whether a redirect response means the next hop has already started (Chrome), see the class comment */
+    private get redirectsStartNextHop();
     static start(connector: BiDiConnector, tree: ContextTree, contextId: string, options?: TrackerOptions): Promise<NetworkTracker>;
     /** Requests currently in flight */
     get inflight(): number;
@@ -52,6 +61,13 @@ export declare class NetworkTracker {
     private owns;
     private static key;
     private onBeforeRequestSent;
+    /** Tracks a new hop and emits its `request`; the hop it was redirected from is done with */
+    private startHop;
+    /**
+     * The hop a response or error is for. A hop Chrome never announced (see the class comment) is started here,
+     * when the hop it was redirected from is known.
+     */
+    private hopOf;
     private onResponseCompleted;
     private onFetchError;
     /**

package/dist/network/network-tracker.js

@@ -12,6 +12,12 @@ const URLS_IN_MESSAGE = 5;
  * Follows the network activity of one page (its frames included): which requests are in flight,
  * and `request` / `response` / `requestfailed` events. In-flight is keyed by `request id:redirect count`,
  * so a redirect chain is one live request at a time.
+ *
+ * Chrome (chromium-bidi) reports a redirect response only once the browser has started the next hop, and it can
+ * leave out that hop's `beforeRequestSent`: when the hop's `requestWillBeSentExtraInfo` reaches it before the
+ * redirect's `requestWillBeSent`, it files the extra info under the previous hop and never announces the new one.
+ * So on Chrome a redirect keeps the chain in flight until the next hop shows itself, and a hop that first shows up
+ * with its response or error is announced then.
  */
 export class NetworkTracker {
     constructor(tree, contextId, ignore, connector) {
@@ -22,7 +28,8 @@ export class NetworkTracker {
         this.events = new EventEmitter();
         /**
          * Every hop that is in flight or may still be the source of a redirect, by hop key. A redirect response ends a
-         * hop's flight (`live` false) but keeps it, for the next hop's `redirectedFrom`.
+         * hop's flight (`live` false; on Chrome `answered`, live until the next hop shows) but keeps it, for the next
+         * hop's `redirectedFrom`.
          */
         this.hops = new Map();
         /** Rejects a pending `waitForIdle`; each wait adds its own */
@@ -31,30 +38,22 @@ export class NetworkTracker {
         this.onBeforeRequestSent = (params) => {
             if (!this.owns(params.context))
                 return;
-            const key = NetworkTracker.key(params.request, params.redirectCount);
-            const { redirectCount } = params;
-            const previousKey = `${params.request.request}:${redirectCount - 1}`;
-            const redirectedFrom = redirectCount > 0 ? (this.hops.get(previousKey)?.request ?? null) : null;
-            this.hops.delete(previousKey);
-            const request = toRequest(params.request, params.navigation, params.isBlocked, redirectedFrom);
-            if (this.ignore(request))
-                return;
-            this.hops.set(key, { request, context: params.context, live: true });
-            this.emit("request", request);
-            this.events.emit("change");
+            this.startHop(params);
         };
         this.onResponseCompleted = (params) => {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const hop = this.hops.get(key);
-            if (!hop?.live)
+            const hop = this.hopOf(params);
+            if (!hop?.live || hop.answered)
                 return;
             const { request } = hop;
             const { response } = params;
             // A redirect response keeps its request around: the next hop links back to it
             if (response.status < 300 || response.status >= 400)
                 this.hops.delete(key);
+            else if (this.redirectsStartNextHop && hasLocation(response))
+                hop.answered = true;
             else
                 hop.live = false;
             this.emit("response", {
@@ -71,11 +70,13 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             const key = NetworkTracker.key(params.request, params.redirectCount);
-            const hop = this.hops.get(key);
+            const hop = this.hopOf(params);
             if (!hop?.live)
                 return;
             this.hops.delete(key);
-            this.emit("requestfailed", Object.assign(hop.request, { errorText: params.errorText }));
+            // A hop that has its response already did not fail
+            if (!hop.answered)
+                this.emit("requestfailed", Object.assign(hop.request, { errorText: params.errorText }));
             this.events.emit("change");
         };
         /**
@@ -86,19 +87,24 @@ export class NetworkTracker {
             if (!this.owns(params.context))
                 return;
             let changed = false;
-            for (const [key, { request, context, live }] of [...this.hops]) {
+            for (const [key, { request, context, live, answered }] of [...this.hops]) {
                 if (!live || request.navigation === params.navigation)
                     continue;
                 if (!this.tree.isWithin(context, params.context))
                     continue;
                 this.hops.delete(key);
-                this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
+                if (!answered)
+                    this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
                 changed = true;
             }
             if (changed)
                 this.events.emit("change");
         };
     }
+    /** Whether a redirect response means the next hop has already started (Chrome), see the class comment */
+    get redirectsStartNextHop() {
+        return this.connector.browserName === "chrome";
+    }
     static async start(connector, tree, contextId, options = {}) {
         const tracker = new NetworkTracker(tree, contextId, options.ignore ?? (() => false), connector);
         // Listen first, then subscribe: nothing can arrive in between
@@ -189,6 +195,41 @@ export class NetworkTracker {
     static key(data, redirectCount) {
         return `${data.request}:${redirectCount}`;
     }
+    /** Tracks a new hop and emits its `request`; the hop it was redirected from is done with */
+    startHop(params) {
+        const key = NetworkTracker.key(params.request, params.redirectCount);
+        const { redirectCount } = params;
+        const previousKey = `${params.request.request}:${redirectCount - 1}`;
+        const previous = redirectCount > 0 ? this.hops.get(previousKey) : undefined;
+        this.hops.delete(previousKey);
+        const request = toRequest(params.request, params.navigation, params.isBlocked, previous?.request ?? null);
+        if (this.ignore(request)) {
+            if (previous?.live)
+                this.events.emit("change");
+            return undefined;
+        }
+        const hop = {
+            request,
+            context: params.context,
+            live: true,
+            answered: false,
+        };
+        this.hops.set(key, hop);
+        this.emit("request", request);
+        this.events.emit("change");
+        return hop;
+    }
+    /**
+     * The hop a response or error is for. A hop Chrome never announced (see the class comment) is started here,
+     * when the hop it was redirected from is known.
+     */
+    hopOf(params) {
+        const hop = this.hops.get(NetworkTracker.key(params.request, params.redirectCount));
+        if (hop || params.redirectCount === 0)
+            return hop;
+        const previousKey = `${params.request.request}:${params.redirectCount - 1}`;
+        return this.hops.has(previousKey) ? this.startHop(params) : undefined;
+    }
     /** A listener that throws must not stop the tracker or the other listeners */
     emit(event, ...args) {
         for (const listener of this.events.listeners(event)) {
@@ -201,3 +242,7 @@ export class NetworkTracker {
         }
     }
 }
+/** Whether a 3xx response says where to go next: only then does the browser follow it */
+function hasLocation(response) {
+    return response.headers.some((header) => header.name.toLowerCase() === "location");
+}

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

@@ -1,8 +1,11 @@
 import type { PickInfo } from "../protocol.js";
 /** Whether a text holds the value of one of the secrets */
 export declare function holdsSecret(secrets: Map<string, string | undefined>): (text: string | undefined) => boolean;
+/** A text with every secret value it holds replaced by the mask, longest value first (as `holdsSecret` finds them) */
+export declare function maskSecrets(secrets: Map<string, string | undefined>): (text: string) => string;
 /**
  * A field may hold an inserted secret: its value (and any text, attribute, class or CSS value holding a secret) is left out,
+ * the output text has the secret masked (Save as output previews on the recorder's side then, see `outputPreview`),
  * and the first matcher follows the Alt+click rule without a value, so neither the page nor the spec gets it.
  */
 export declare function withoutSecrets(info: PickInfo & {

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

@@ -1,11 +1,20 @@
+import { MASK } from "../../../config/mask.js";
 import { expectationFor } from "../../expectation.js";
 /** Whether a text holds the value of one of the secrets */
 export function holdsSecret(secrets) {
     const values = [...secrets.values()].filter((value) => value !== undefined && value !== "");
     return (text) => text !== undefined && values.some((value) => text.includes(value));
 }
+/** A text with every secret value it holds replaced by the mask, longest value first (as `holdsSecret` finds them) */
+export function maskSecrets(secrets) {
+    const values = [...secrets.values()]
+        .filter((value) => value !== undefined && value !== "")
+        .sort((a, b) => b.length - a.length);
+    return (text) => values.reduce((masked, value) => masked.split(value).join(MASK), text);
+}
 /**
  * A field may hold an inserted secret: its value (and any text, attribute, class or CSS value holding a secret) is left out,
+ * the output text has the secret masked (Save as output previews on the recorder's side then, see `outputPreview`),
  * and the first matcher follows the Alt+click rule without a value, so neither the page nor the spec gets it.
  */
 export function withoutSecrets(info, secrets) {
@@ -24,7 +33,8 @@ export function withoutSecrets(info, secrets) {
     return {
         ...rest,
         text,
-        outputText: secret(info.outputText) ? "" : info.outputText,
+        outputText: maskSecrets(secrets)(info.outputText),
+        ...(secret(info.outputText) && { showsSecret: true }),
         attributes: info.attributes.filter((a) => !secret(a.value)),
         className: secret(info.className ?? undefined) ? null : info.className,
         css: secret(info.css.value) ? { ...info.css, value: "" } : info.css,

package/dist/recorder/toolbar/actions/save-output.d.ts

@@ -1,9 +1,15 @@
-import type { ActionReply } from "../protocol.js";
+import type { ActionReply, OutputPreview } from "../protocol.js";
 import type { ActionContext, Of } from "../types.js";
 /**
- * Turns the Save as output panel's choice into a `saveOutput` step for the element that was picked. Refuses an
- * element whose text holds a secret, a name `test()` would reject, an element with no text when there is no
- * pattern, and a pattern that isn't valid or doesn't match the element's text as picked, read the way
- * `outputs.save` reads it.
+ * What Save as output would save from an element that shows a secret, worked out here because the page only has
+ * its text masked: `outputs.save`'s rule (the first group, else the whole match, else the whole text) on the text
+ * as picked, every secret masked, and whether the value held one. The errors read as the panel's own preview's.
+ */
+export declare function outputPreview(ctx: ActionContext, message: Of<"output-preview">): OutputPreview;
+/**
+ * Turns the Save as output panel's choice into a `saveOutput` step for the element that was picked. Refuses a
+ * name `test()` would reject, an element with no text when there is no pattern, and a pattern that isn't valid
+ * or doesn't match the element's text as picked, read the way `outputs.save` reads it. An element that shows a
+ * secret is saved too: the panel warns that the output may hold it.
  */
 export declare function saveOutputAction(ctx: ActionContext, message: Of<"save-output">): Promise<ActionReply>;

package/dist/recorder/toolbar/actions/save-output.js

@@ -1,38 +1,65 @@
-import { matchesText } from "../../../assert/text-match.js";
-import { holdsSecret } from "./pick.js";
+import { captured, matchesText } from "../../../assert/text-match.js";
+import { holdsSecret, maskSecrets } from "./pick.js";
 import { fail, nameProblem, PAUSED } from "./reply.js";
+const PICK_AGAIN = "Pick the element again";
+/** A pattern as typed, compiled the way the step writes it; undefined when there is none, an error when it isn't valid */
+function compile(pattern) {
+    const source = String(pattern ?? "").trim();
+    if (source === "")
+        return undefined;
+    try {
+        return new RegExp(source);
+    }
+    catch {
+        return { error: "pattern is not a valid regular expression" };
+    }
+}
 /**
- * Turns the Save as output panel's choice into a `saveOutput` step for the element that was picked. Refuses an
- * element whose text holds a secret, a name `test()` would reject, an element with no text when there is no
- * pattern, and a pattern that isn't valid or doesn't match the element's text as picked, read the way
- * `outputs.save` reads it.
+ * What Save as output would save from an element that shows a secret, worked out here because the page only has
+ * its text masked: `outputs.save`'s rule (the first group, else the whole match, else the whole text) on the text
+ * as picked, every secret masked, and whether the value held one. The errors read as the panel's own preview's.
+ */
+export function outputPreview(ctx, message) {
+    const pattern = String(message.pattern ?? "");
+    const answer = { preview: true, pattern };
+    const pick = ctx.pick();
+    if (!pick || pick.id !== message.id)
+        return { ...answer, ok: false, error: PICK_AGAIN };
+    const compiled = compile(pattern);
+    if (compiled && !(compiled instanceof RegExp))
+        return { ...answer, ok: false, error: "Not a valid pattern" };
+    if (compiled && !matchesText(pick.text, compiled, "exact"))
+        return { ...answer, ok: false, error: "No match" };
+    const value = compiled ? captured(compiled, pick.text) : pick.text;
+    return {
+        ...answer,
+        ok: true,
+        value: maskSecrets(ctx.secrets)(value),
+        secret: holdsSecret(ctx.secrets)(value),
+    };
+}
+/**
+ * Turns the Save as output panel's choice into a `saveOutput` step for the element that was picked. Refuses a
+ * name `test()` would reject, an element with no text when there is no pattern, and a pattern that isn't valid
+ * or doesn't match the element's text as picked, read the way `outputs.save` reads it. An element that shows a
+ * secret is saved too: the panel warns that the output may hold it.
  */
 export async function saveOutputAction(ctx, message) {
     if (ctx.isPaused())
         return fail(PAUSED);
     const pick = ctx.pick();
     if (!pick || pick.id !== message.id)
-        return fail("Pick the element again");
-    // The step would write the secret into the run's results
-    if (holdsSecret(ctx.secrets)(pick.text))
-        return fail("this element shows a secret; it can't be an output");
+        return fail(PICK_AGAIN);
     const name = String(message.name ?? "").trim();
     const problem = nameProblem(name);
     if (problem)
         return fail(problem, "name");
-    const source = String(message.pattern ?? "").trim();
-    let pattern;
-    if (source !== "") {
-        try {
-            pattern = new RegExp(source);
-        }
-        catch {
-            return fail("pattern is not a valid regular expression");
-        }
-        if (!matchesText(pick.text, pattern, "exact"))
-            return fail("pattern doesn't match the element's text");
-    }
-    else if (pick.text === "")
+    const pattern = compile(message.pattern);
+    if (pattern && !(pattern instanceof RegExp))
+        return fail(pattern.error);
+    if (pattern && !matchesText(pick.text, pattern, "exact"))
+        return fail("pattern doesn't match the element's text");
+    if (!pattern && pick.text === "")
         return fail("the element has no text");
     ctx.setPick(undefined);
     ctx.deps.observe({

package/dist/recorder/toolbar/controller.js

@@ -4,7 +4,7 @@ import { assertAction } from "./actions/assert.js";
 import { assertPageAction, pageInfoOf } from "./actions/assert-page.js";
 import { addInsertableAction, insertAction } from "./actions/insert.js";
 import { withoutSecrets } from "./actions/pick.js";
-import { saveOutputAction } from "./actions/save-output.js";
+import { outputPreview, saveOutputAction } from "./actions/save-output.js";
 import { fail, PAUSED, UNIDENTIFIABLE } from "./actions/reply.js";
 import { insertablesOf } from "./insertables.js";
 import { LEFT, PageScope } from "./page-scope.js";
@@ -148,6 +148,8 @@ export class ToolbarController {
                 return this.replying(message, () => addInsertableAction(this.actions, message));
             case "save-output":
                 return this.replying(message, () => saveOutputAction(this.actions, message));
+            case "output-preview":
+                return this.reply(message.id, outputPreview(this.actions, message));
             case "wait":
                 if (this.paused)
                     return;

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

@@ -118,6 +118,12 @@ export type ToolbarMessage = {
     name: string;
     pattern?: string;
 }
+/** The pattern of Save as output for an element that shows a secret, as typed: answered with an `OutputPreview` */
+ | {
+    action: "output-preview";
+    id: number;
+    pattern: string;
+}
 /** The Page panel opened: answered with a `PageInfo` */
  | {
     action: "page-info";
@@ -148,6 +154,8 @@ export type PickInfo = {
     text: string;
     /** The whole text as `outputs.save` reads it (`textContent`, trimmed): what Save as output captures from */
     outputText: string;
+    /** `outputText` held a secret, which is masked in it: Save as output asks the recorder for its preview */
+    showsSecret?: true;
     value?: string;
     attributes: {
         name: string;
@@ -186,6 +194,21 @@ export type PageInfo = {
     ok: false;
     error: string;
 };
+/**
+ * The answer to `output-preview`: what `outputs.save` would keep from the element's real text with `pattern`,
+ * every secret masked; `secret` when the value held one. `pattern` is the one asked about, so a late answer is dropped.
+ */
+export type OutputPreview = {
+    preview: true;
+    pattern: string;
+} & ({
+    ok: true;
+    value: string;
+    secret: boolean;
+} | {
+    ok: false;
+    error: string;
+});
 /** The answer to `insert`, `add-insertable`, `assert`, `assert-page` and `save-output` */
 export type ActionReply = {
     ok: true;

package/dist/recorder/toolbar/source/fields.js

@@ -16,7 +16,10 @@ export const FIELDS_JS = String.raw `  const press = (action, detail) => {
       if (ui.output[key] === value) return;
       ui.output[key] = value;
       if (key === "name") ui.output.nameError = null;
-      else ui.output.error = null;
+      else {
+        ui.output.error = null;
+        if (ui.output.info && ui.output.info.ok && ui.output.info.showsSecret) askPreview(ui.output);
+      }
       render();
     }
     else if (field === "attribute" && ui.assert) {

package/dist/recorder/toolbar/source/picking.js

@@ -63,7 +63,7 @@ export const PICKING_JS = String.raw `  // ---- Panels and picking ----
     const r = target.getBoundingClientRect();
     const rect = { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
     if (ui.pickFor === "output") {
-      ui.output = { id, target, candidates, info: null, name: "", pattern: "", nameError: null, error: null, rect };
+      ui.output = { id, target, candidates, info: null, name: "", pattern: "", preview: null, nameError: null, error: null, rect };
     } else {
       ui.assert = {
         id, target, candidates, info: null, matcher: "toBeVisible", expected: "", attribute: null, countIndex: 0,

package/dist/recorder/toolbar/source/recorder-side.js

@@ -27,6 +27,13 @@ export const RECORDER_SIDE_JS = String.raw `  // ---- The recorder's side ----
     render();
   };
   const reply = (id, result) => {
+    // A Save as output preview, for the pattern still typed (a late one is dropped); it doesn't end a pending action
+    if (result && result.preview) {
+      const o = ui.panel === "output" && ui.output;
+      if (!o || o.id !== id || o.pattern.trim() !== result.pattern) return;
+      o.preview = result;
+      return render();
+    }
     if (!ui.pending || id !== ui.pending || !result) return;
     ui.busy = false;
     const ok = result.ok === true;
@@ -44,6 +51,7 @@ export const RECORDER_SIDE_JS = String.raw `  // ---- The recorder's side ----
     } else if (ui.panel === "output" && ui.output && !ui.output.info) {
       ui.output.info = result;
       if (ok) ui.focus = "outputName";
+      if (ok && result.showsSecret) askPreview(ui.output);
     } else if (ui.panel === "page" && ui.page && !ui.page.info) {
       ui.page.info = result;
       if (ok) {

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

@@ -82,17 +82,28 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
     if (!match) return { error: "No match" };
     return { value: match[1] !== undefined ? match[1] : match[0] };
   };
+  // An element that shows a secret reaches the page with it masked: the recorder works out its preview from the real text
+  const askPreview = (o) => {
+    o.preview = null;
+    post({ action: "output-preview", id: o.id, pattern: o.pattern.trim() });
+  };
+  const outputCapture = (o) => {
+    if (!o.info.showsSecret) return captureOf(o.info.outputText, o.pattern);
+    if (!o.preview) return { value: "…" };
+    return o.preview.ok ? { value: o.preview.value, secret: o.preview.secret } : { error: o.preview.error };
+  };
   const outputPanel = () => {
     const o = ui.output;
     const info = o.info;
     const head = h("div", { class: "h" }, "Save as output", info && info.ok && h("code", { title: info.label }, info.label));
     if (!info) return [head, h("div", { class: "msg" }, "…")];
     if (!info.ok) return [head, h("div", { class: "err" }, info.error)];
-    const capture = captureOf(info.outputText, o.pattern);
+    const capture = outputCapture(o);
     return [
       head,
+      info.showsSecret && h("div", { class: "warn out-secret" }, "This element shows a secret. The saved output may contain it; use a pattern that captures only the non-secret part."),
       h("div", { class: "lbl" }, "Text"),
-      h("div", { class: "msg out-text" }, info.text),
+      h("div", { class: "msg out-text" }, info.showsSecret ? info.outputText : info.text),
       h("div", { class: "lbl" }, "Name"),
       h("div", { class: "f" }, h("input", { type: "text", class: "in code", "data-field": "outputName", value: o.name, "data-enter": "output-save", autocomplete: "off", spellcheck: "false" })),
       o.nameError && h("div", { class: "field-error" }, o.nameError),
@@ -100,6 +111,7 @@ export const VIEWS_PANELS_JS = String.raw `  const unavailable = (info, matcher)
       h("div", { class: "f" }, h("input", { type: "text", class: "in code", "data-field": "outputPattern", value: o.pattern, placeholder: "Order #(\\d+)", "data-enter": "output-save", autocomplete: "off", spellcheck: "false" })),
       h("div", { class: "lbl" }, "Saves"),
       capture.error ? h("div", { class: "warn out-capture" }, capture.error) : h("code", { class: "out-capture" }, capture.value),
+      capture.secret && h("div", { class: "err out-leak" }, "The output will contain a secret: reports mask it, but whatever reads the output gets the real value."),
       o.error && h("div", { class: "err" }, o.error),
       h("div", { class: "foot" }, h("button", { class: "add", "data-action": "output-save", disabled: ui.busy || !o.name.trim() }, "Save")),
     ];

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

@@ -9,7 +9,8 @@
  * `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`, `add-insertable` and `save-output` (an `ActionReply`).
+ *   `assert-page`, `insert`, `add-insertable` and `save-output` (an `ActionReply`), or to `output-preview` (an
+ *   `OutputPreview`, which carries `preview: true` and doesn't end a pending action).
  * - `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);

package/dist/recorder/toolbar/source.js

@@ -24,7 +24,8 @@ 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`, `add-insertable` and `save-output` (an `ActionReply`).
+ *   `assert-page`, `insert`, `add-insertable` and `save-output` (an `ActionReply`), or to `output-preview` (an
+ *   `OutputPreview`, which carries `preview: true` and doesn't end a pending action).
  * - `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);

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

@@ -1,7 +1,7 @@
 import type { ElementHandle } from "../../script/element-handle.js";
 import type { LocatorCall, LocatorSpec } from "../../steps/model.js";
 import type { Observation } from "../normalise.js";
-import type { ActionReply, PageInfo, PickInfo, ToolbarMessage, ToolbarState } from "./protocol.js";
+import type { ActionReply, OutputPreview, PageInfo, PickInfo, ToolbarMessage, ToolbarState } from "./protocol.js";
 /** What `inspect` found for a picked element: the reply, and the locator behind each Count choice */
 export interface Inspection {
     info: PickInfo & {
@@ -14,7 +14,7 @@ export interface Inspection {
 export interface ControllerDeps {
     /** Sends the state to every loaded top-level document's toolbar */
     push(state: ToolbarState): void;
-    reply(id: number, result: PickInfo | PageInfo | ActionReply): void;
+    reply(id: number, result: PickInfo | PageInfo | ActionReply | OutputPreview): void;
     currentUrl(): Promise<string>;
     /** The recorded page's URL and title */
     pageInfo(): Promise<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {
@@ -57,11 +57,15 @@
   "scripts": {
     "dev": "tsx src/index.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-types.mjs",
+    "build-watch": "node scripts/copy-types.mjs && tsc -w --preserveWatchOutput -p tsconfig.build.json",
     "prepack": "npm run build",
+    "typecheck": "tsc --noEmit --noUnusedLocals",
     "test": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-timeout=10000 \"src/**/*.test.ts\"",
-    "test:browser": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 --test-timeout=60000 ${SAMURAI_TEST_SHARD:+--test-shard=$SAMURAI_TEST_SHARD} \"src/**/*.browser-test.ts\"",
-    "test:browser:chrome": "SAMURAI_TEST_BROWSER=chrome npm run test:browser",
-    "test:cli": "tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 \"src/**/*.cli-test.ts\""
+    "test-browser": "SAMURAI_LOG_LEVEL=${SAMURAI_LOG_LEVEL:-warn} tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 --test-timeout=60000 $(node scripts/browser-shards.mjs)",
+    "test-browser-chrome": "SAMURAI_TEST_BROWSER=chrome bun run test-browser",
+    "test-cli": "tsx --import ./scripts/test-tmp.mjs --test --test-concurrency=1 \"src/**/*.cli-test.ts\"",
+    "knip": "knip --no-config-hints",
+    "madge": "madge --circular src"
   },
   "keywords": [
     "testing",
@@ -77,6 +81,8 @@
   "devDependencies": {
     "@types/node": "^25.6.0",
     "esbuild": "^0.28.2",
+    "knip": "^6.42.1",
+    "madge": "^8.0.0",
     "tsx": "^4.23.15"
   },
   "dependencies": {
@@ -113,5 +119,39 @@
   },
   "engines": {
     "node": ">=24"
+  },
+  "nx": {
+    "name": "framework",
+    "targets": {
+      "test": {
+        "dependsOn": [
+          "build"
+        ]
+      },
+      "test-cli": {
+        "dependsOn": [
+          "build"
+        ],
+        "cache": true,
+        "parallelism": false
+      },
+      "test-browser": {
+        "cache": true,
+        "parallelism": false,
+        "inputs": [
+          "default",
+          {
+            "env": "SAMURAI_TEST_BROWSER"
+          },
+          {
+            "env": "SAMURAI_TEST_SHARD"
+          }
+        ]
+      },
+      "build-watch": {
+        "continuous": true,
+        "cache": false
+      }
+    }
   }
 }