@itmetsam/samurai-framework 0.9.0 → 0.12.0

package/dist/recorder/normalise.js

@@ -1,24 +1,6 @@
-const TEXT_LIMIT = 100;
+import { expectationFor, secretNameFor } from "./expectation.js";
 /** A picker that opens within this many ms of a click was opened by it */
-export const PICKER_WINDOW = 1000;
-/** The name a secret gets in `secrets.<NAME>`: the field's name or id, upper snake case */
-export function secretNameFor(hint) {
-    const name = (hint ?? "")
-        .replace(/([a-z\d])([A-Z])/g, "$1_$2")
-        .replace(/[^A-Za-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "")
-        .toUpperCase();
-    return name === "" || /^\d/.test(name) ? "PASSWORD" : name;
-}
-export function expectationFor(text, value) {
-    if (value !== undefined)
-        return { matcher: "toHaveValue", expected: value };
-    if (text === "")
-        return { matcher: "toBeVisible" };
-    return text.length <= TEXT_LIMIT
-        ? { matcher: "toHaveText", expected: text }
-        : { matcher: "toContainText", expected: text.slice(0, TEXT_LIMIT).trim() };
-}
+const PICKER_WINDOW = 1000;
 /**
  * Turns what the tester did into steps:
  * - typing into a field becomes one `fill`, rewritten as the text grows (a password becomes a secret reference);
@@ -93,82 +75,105 @@ export class Normaliser {
             this.lastFill = undefined;
             return [this.insert(fromToolbar)];
         }
-        // The sandbox reports a picker for any click on a file input, including ones a page script fires:
-        // it is only a hint, and only the very last step, recorded just before, may be replaced or removed
-        // (a page's own input.click() also counts as the opening click, bounded to the last step within PICKER_WINDOW)
-        if (observation.type === "picker") {
-            const click = this.lastClick;
-            this.picker =
-                click && click.index === this.next - 1 && at - click.at <= PICKER_WINDOW
-                    ? click.index
-                    : undefined;
-            return [];
+        switch (observation.type) {
+            case "picker":
+                return this.pickerOpened(at);
+            case "picker-cancel":
+                return this.pickerCancelled();
+            case "files":
+                return this.filesSet(observation, at);
+            case "click":
+                return this.clicked(observation, at);
+            case "press":
+                return this.pressed(observation, at);
+            case "assert":
+                return this.asserted(observation);
+            case "input":
+                return this.typed(observation, at);
+            default:
+                return [];
         }
-        if (observation.type === "picker-cancel") {
-            const index = this.picker;
+    }
+    /**
+     * The sandbox reports a picker for any click on a file input, including ones a page script fires: it is only a
+     * hint, and only the very last step, recorded just before, may be replaced or removed (a page's own
+     * input.click() also counts as the opening click, bounded to the last step within PICKER_WINDOW)
+     */
+    pickerOpened(at) {
+        const click = this.lastClick;
+        this.picker =
+            click && click.index === this.next - 1 && at - click.at <= PICKER_WINDOW
+                ? click.index
+                : undefined;
+        return [];
+    }
+    /** The picker closed without a choice: the click that opened it is taken out again */
+    pickerCancelled() {
+        const index = this.picker;
+        this.picker = undefined;
+        if (index === undefined || index !== this.next - 1)
+            return [];
+        this.next--;
+        this.lastClick = undefined;
+        this.lastStep = undefined;
+        return [{ op: "remove", index }];
+    }
+    filesSet(observation, at) {
+        this.lastFill = undefined;
+        this.lastAction = at;
+        const step = {
+            kind: observation.via === "drop" ? "dropFiles" : "setInputFiles",
+            locator: observation.locator,
+            files: observation.files,
+        };
+        const index = this.picker;
+        if (observation.via === "input" &&
+            index !== undefined &&
+            index === this.next - 1) {
             this.picker = undefined;
-            if (index === undefined || index !== this.next - 1)
-                return [];
-            this.next--;
             this.lastClick = undefined;
-            this.lastStep = undefined;
-            return [{ op: "remove", index }];
+            this.lastStep = step;
+            return [{ op: "replace", index, step }];
         }
-        if (observation.type === "files") {
-            this.lastFill = undefined;
-            this.lastAction = at;
-            const step = {
-                kind: observation.via === "drop" ? "dropFiles" : "setInputFiles",
+        return [this.insert(step)];
+    }
+    clicked(observation, at) {
+        if (observation.textEntry)
+            return []; // focusing a field: the fill that follows needs no click
+        this.lastFill = undefined;
+        this.lastAction = at;
+        const events = [
+            this.insert({ kind: "click", locator: observation.locator }),
+        ];
+        this.lastClick = { index: this.next - 1, at };
+        return events;
+    }
+    pressed(observation, at) {
+        // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
+        this.lastFill = undefined;
+        this.lastAction = at;
+        return [
+            this.insert({
+                kind: "press",
                 locator: observation.locator,
-                files: observation.files,
-            };
-            const index = this.picker;
-            if (observation.via === "input" &&
-                index !== undefined &&
-                index === this.next - 1) {
-                this.picker = undefined;
-                this.lastClick = undefined;
-                this.lastStep = step;
-                return [{ op: "replace", index, step }];
-            }
-            return [this.insert(step)];
-        }
-        if (observation.type === "click") {
-            if (observation.textEntry)
-                return []; // focusing a field: the fill that follows needs no click
-            this.lastFill = undefined;
-            this.lastAction = at;
-            const events = [
-                this.insert({ kind: "click", locator: observation.locator }),
-            ];
-            this.lastClick = { index: this.next - 1, at };
-            return events;
-        }
-        if (observation.type === "press") {
-            // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
-            this.lastFill = undefined;
-            this.lastAction = at;
-            return [
-                this.insert({
-                    kind: "press",
-                    locator: observation.locator,
-                    key: observation.pressed,
-                }),
-            ];
-        }
-        if (observation.type === "assert") {
-            this.lastFill = undefined;
-            return [
-                this.insert({
-                    kind: "expect",
-                    locator: observation.locator,
-                    not: false,
-                    expectation: expectationFor(observation.text, observation.value),
-                }),
-            ];
-        }
-        if (observation.type !== "input")
-            return [];
+                key: observation.pressed,
+            }),
+        ];
+    }
+    /** An Alt+click */
+    asserted(observation) {
+        this.lastFill = undefined;
+        return [
+            this.insert({
+                kind: "expect",
+                locator: observation.locator,
+                not: false,
+                expectation: expectationFor(observation.text, observation.value),
+            }),
+        ];
+    }
+    /** Typing: one `fill` per field, rewritten as the text grows */
+    typed(observation, at) {
         this.lastAction = at;
         const step = {
             kind: "fill",

package/dist/recorder/options.d.ts

@@ -0,0 +1,56 @@
+import type { RecorderEvent } from "./normalise.js";
+import type { ControllerDeps, ControllerOptions } from "./toolbar/types.js";
+/** The toolbar's settings: the recording's environment, and where its variables and secrets are written */
+export type ToolbarOptions = ControllerOptions & {
+    /** The project folder: `samurai.config.ts` and `.env.<environment>` */
+    projectDir: string;
+    /**
+     * Called when the recording is paused or resumed, or the toolbar fails (or comes back) on a page.
+     * There is no initial call: until the first one the recording is `{ state: "recording", toolbar: true }`
+     */
+    onStatus?: ControllerDeps["onStatus"];
+    /** A secret was saved to `.env.<environment>` from the panel (before its value is typed) */
+    onSecretAdded?: (name: string) => void;
+    /**
+     * The toolbar's Stop; the caller then stops the recording (`recorder.stop()`), as `recordSpec` does.
+     * Without it, Stop runs `recorder.stop()` itself: the toolbar goes away and nothing more is recorded, but
+     * nothing tells the `page.record()` caller, so pass `onStop` to learn of it.
+     */
+    onStop?: () => void;
+};
+/** Where uploads made while recording are stored */
+export interface FileRecording {
+    /** The project folder */
+    projectDir: string;
+    /** Relative to the project folder. @default "files" */
+    filesDir?: string;
+    /** A file that isn't stored (over 50 MB, or unreadable): its step points at `path`, which doesn't exist */
+    onMissing?: (file: MissingFile) => void;
+    /** @internal Tests only: also record events no person caused (`isTrusted` false) */
+    trustSynthetic?: boolean;
+}
+export interface MissingFile {
+    /** Project-relative, as the step has it */
+    path: string;
+    name: string;
+    size: number;
+    reason: "too-big" | "unreadable";
+}
+export interface RecorderOptions {
+    /** Called for every step the tester produces, in order. Steps get indexes from `at` on */
+    onEvent: (event: RecorderEvent) => void;
+    /**
+     * Index the first recorded step gets: record from the middle of a test by passing the number of steps
+     * before it. The page must already be in the state those steps lead to; replaying them is up to the caller.
+     * @default 0
+     */
+    at?: number;
+    /** Write the page the recording starts on as a `goto` step. Pass false when `at` > 0. @default true */
+    initialGoto?: boolean;
+    /** URLs inside it are written relative to it, as `page.goto` resolves them */
+    baseURL?: string;
+    /** Shows the recorder toolbar in the page (pause, assert, insert, wait, screenshot, stop). Without it, no toolbar */
+    toolbar?: ToolbarOptions;
+    /** Records uploads (file inputs and drops) into the project's files folder. Without it, uploads aren't recorded */
+    files?: FileRecording;
+}

package/dist/recorder/options.js

@@ -0,0 +1 @@
+export {};

package/dist/recorder/page-messages.d.ts

@@ -0,0 +1,35 @@
+import type { ElementHandle } from "../script/element-handle.js";
+import type { LocatorCall, LocatorSpec } from "../steps/model.js";
+import type { Observation } from "./normalise.js";
+/** What the files capture script sends */
+export type FilesMessage = {
+    type: "picker";
+} | {
+    type: "picker-cancel";
+} | {
+    type: "files";
+    via: "input" | "drop";
+    target: ElementHandle;
+    candidates: LocatorCall[];
+    files: {
+        id: number;
+        name: string;
+        type: string;
+        size: number;
+    }[];
+};
+/** What the capture script sends */
+export interface PageMessage {
+    type: "click" | "input" | "press" | "assert";
+    target: ElementHandle;
+    candidates: LocatorCall[];
+    textEntry?: boolean;
+    /** The key of a `press` message */
+    pressed?: string;
+    value?: string;
+    secret?: boolean;
+    secretName?: string;
+    text?: string;
+}
+/** What a page message says, as the normaliser takes it once its element has a locator */
+export declare function observationFor(message: PageMessage, locator: LocatorSpec): Observation;

package/dist/recorder/page-messages.js

@@ -0,0 +1,26 @@
+/** What a page message says, as the normaliser takes it once its element has a locator */
+export function observationFor(message, locator) {
+    const key = message.target.sharedId;
+    return message.type === "click"
+        ? { type: "click", key, locator, textEntry: message.textEntry === true }
+        : message.type === "press"
+            ? { type: "press", key, locator, pressed: message.pressed ?? "" }
+            : message.type === "assert"
+                ? {
+                    type: "assert",
+                    key,
+                    locator,
+                    text: message.text ?? "",
+                    ...(message.value !== undefined && { value: message.value }),
+                }
+                : {
+                    type: "input",
+                    key,
+                    locator,
+                    ...(message.value !== undefined && { value: message.value }),
+                    ...(message.secret && { secret: true }),
+                    ...(message.secretName !== undefined && {
+                        secretName: message.secretName,
+                    }),
+                };
+}

package/dist/recorder/ranking.js

@@ -7,6 +7,7 @@ import { locatorFromSpec } from "../steps/build.js";
 export async function rankLocator(page, target, candidates, maxFallbacks = 2) {
     const verified = [];
     for (const candidate of candidates) {
+        // The primary plus `maxFallbacks` fallbacks: stop once one more than that is verified
         if (verified.length > maxFallbacks)
             break;
         const found = await locatorFromSpec(page, {

package/dist/recorder/realms.d.ts

@@ -0,0 +1,6 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/**
+ * The window realms of `sandbox` in the context, as the browser lists them now. A script message names the realm it
+ * came from; only messages from a sandbox the page cannot reach are taken.
+ */
+export declare function listSandboxRealms(connector: BiDiConnector, context: string, sandbox: string): Promise<Set<string>>;

package/dist/recorder/realms.js

@@ -0,0 +1,13 @@
+/**
+ * The window realms of `sandbox` in the context, as the browser lists them now. A script message names the realm it
+ * came from; only messages from a sandbox the page cannot reach are taken.
+ */
+export async function listSandboxRealms(connector, context, sandbox) {
+    const { realms } = await connector.send("script.getRealms", {
+        context,
+        type: "window",
+    });
+    return new Set(realms
+        .filter((info) => info.type === "window" && info.sandbox === sandbox)
+        .map((info) => info.realm));
+}

package/dist/recorder/recorder.d.ts

@@ -1,62 +1,10 @@
 import type Page from "../browser/page.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { type RecorderEvent } from "./normalise.js";
-import { type ControllerDeps, type ControllerOptions } from "./toolbar/controller.js";
+import { missingFileText } from "./files-recorder.js";
+import type { MissingFile, RecorderOptions } from "./options.js";
 export type { RecorderEvent } from "./normalise.js";
-/** The toolbar's settings: the recording's environment, and where its variables and secrets are written */
-export type ToolbarOptions = ControllerOptions & {
-    /** The project folder: `samurai.config.ts` and `.env.<environment>` */
-    projectDir: string;
-    /**
-     * Called when the recording is paused or resumed, or the toolbar fails (or comes back) on a page.
-     * There is no initial call: until the first one the recording is `{ state: "recording", toolbar: true }`
-     */
-    onStatus?: ControllerDeps["onStatus"];
-    /** A secret was saved to `.env.<environment>` from the panel (before its value is typed) */
-    onSecretAdded?: (name: string) => void;
-    /**
-     * The toolbar's Stop; the caller then stops the recording (`recorder.stop()`), as `recordSpec` does.
-     * Without it, Stop runs `recorder.stop()` itself: the toolbar goes away and nothing more is recorded, but
-     * nothing tells the `page.record()` caller, so pass `onStop` to learn of it.
-     */
-    onStop?: () => void;
-};
-/** Where uploads made while recording are stored */
-export interface FileRecording {
-    /** The project folder */
-    projectDir: string;
-    /** Relative to the project folder. @default "files" */
-    filesDir?: string;
-    /** A file that isn't stored (over 50 MB, or unreadable): its step points at `path`, which doesn't exist */
-    onMissing?: (file: MissingFile) => void;
-    /** @internal Tests only: also record events no person caused (`isTrusted` false) */
-    trustSynthetic?: boolean;
-}
-export interface MissingFile {
-    /** Project-relative, as the step has it */
-    path: string;
-    name: string;
-    size: number;
-    reason: "too-big" | "unreadable";
-}
-export interface RecorderOptions {
-    /** Called for every step the tester produces, in order. Steps get indexes from `at` on */
-    onEvent: (event: RecorderEvent) => void;
-    /**
-     * Index the first recorded step gets: record from the middle of a test by passing the number of steps
-     * before it. The page must already be in the state those steps lead to; replaying them is up to the caller.
-     * @default 0
-     */
-    at?: number;
-    /** Write the page the recording starts on as a `goto` step. Pass false when `at` > 0. @default true */
-    initialGoto?: boolean;
-    /** URLs inside it are written relative to it, as `page.goto` resolves them */
-    baseURL?: string;
-    /** Shows the recorder toolbar in the page (pause, assert, insert, wait, screenshot, stop). Without it, no toolbar */
-    toolbar?: ToolbarOptions;
-    /** Records uploads (file inputs and drops) into the project's files folder. Without it, uploads aren't recorded */
-    files?: FileRecording;
-}
+export type { FileRecording, MissingFile, RecorderOptions, ToolbarOptions, } from "./options.js";
+export { missingFileText };
 /**
  * Watches the tester use the page and reports steps as they happen. A preload script reports clicks,
  * typing and Alt+click assertions over a `script.message` channel; each element is given locators that
@@ -78,23 +26,19 @@ export declare class Recorder {
     /** Set when stopping begins: files messages after it are not taken */
     private ending;
     private stopping;
-    private controller;
+    private toolbar;
+    private files;
     private constructor();
     /** The files capture script's channel, handed only to its sandbox */
     private readonly filesChannel;
     private filesPreload;
     private filesRealms;
-    private readonly stored;
-    private readonly missing;
+    /** The toolbar's controller, when the recording has a toolbar */
+    private get controller();
     /** Files stored or reused in the files folder by this recording, project-relative */
     get storedFiles(): string[];
     /** Files whose steps point at a path that wasn't written */
     get missingFiles(): MissingFile[];
-    /** The context's `samurai-toolbar` sandbox realms, as last listed: the only realms toolbar messages are taken from */
-    private toolbarRealms;
-    /** Toolbar messages waiting for a realm lookup, and those that arrived behind them (kept in order) */
-    private toolbarBacklog;
-    private toolbarWaiting;
     static start(target: {
         page: Page;
         connector: BiDiConnector;
@@ -108,25 +52,19 @@ export declare class Recorder {
      */
     private readonly onMessage;
     private listFilesRealms;
-    private listToolbarRealms;
-    /** A message from the toolbar's own sandbox */
-    private fromToolbar;
     private readonly onLoad;
     private readonly onNavigation;
     private subscription;
     private preload;
     private toolbarPreload;
     private begin;
-    private createController;
-    /** Calls the toolbar hook's `method` in the loaded document; a document between loads has no toolbar yet */
-    private callToolbar;
+    private createToolbar;
+    private createFiles;
     private enqueue;
     private emit;
     private locatorFor;
     private handle;
     private fromFiles;
-    /** Saves one kept file to the files folder; returns the path its step gets */
-    private storePageFile;
     private release;
     /**
      * Pauses capture in the loaded document: clicks and typing are not reported until `unmute`.
@@ -140,5 +78,3 @@ export declare class Recorder {
     stop(): Promise<void>;
     private end;
 }
-/** The warning for a file that isn't saved, as the toolbar and the CLI show it */
-export declare function missingFileText(file: MissingFile, folder: string): string;