@itmetsam/samurai-framework 0.5.0 → 0.7.0

package/dist/recorder/recorder.js

@@ -1,39 +1,99 @@
 import { randomUUID } from "node:crypto";
 import logger from "../logger/index.js";
 import { addPreload, runInLoadedContexts } from "../script/preload.js";
+import { callFunction } from "../script/call-function.js";
 import { ChannelArg, fromRemoteValue } from "../script/serialize.js";
 import { ElementHandle } from "../script/element-handle.js";
-import { CAPTURE_OFF, CAPTURE_SOURCE } from "./capture.js";
+import { locatorFromSpec } from "../steps/build.js";
+import { addVariable, setSecret } from "../project/index.js";
+import { CAPTURE_MUTE, CAPTURE_OFF, CAPTURE_SOURCE, CAPTURE_UNMUTE, } from "./capture.js";
 import { Normaliser, } from "./normalise.js";
 import { rankLocator } from "./ranking.js";
+import { ToolbarController, } from "./toolbar/controller.js";
+import { inspectElement } from "./toolbar/inspect.js";
+import { TOOLBAR_KEY, TOOLBAR_SANDBOX, } from "./toolbar/protocol.js";
+import { TOOLBAR_SOURCE } from "./toolbar/source.js";
+/** The toolbar's hook in its sandbox */
+const HOOK = `globalThis[Symbol.for(${JSON.stringify(TOOLBAR_KEY)})]`;
 /**
  * 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
  * were checked against the page; the normaliser turns the stream into steps.
  */
 export class Recorder {
-    constructor(page, connector, context, normaliser, options, channel) {
+    constructor(page, connector, context, normaliser, options, 
+    /** The capture script's channel: page messages only */
+    channel, 
+    /** The toolbar's channel, handed only to the toolbar's sandbox: toolbar messages only */
+    toolbarChannel) {
         this.page = page;
         this.connector = connector;
         this.context = context;
         this.normaliser = normaliser;
         this.options = options;
         this.channel = channel;
+        this.toolbarChannel = toolbarChannel;
         this.queue = { tail: Promise.resolve() };
         this.known = new Map();
         this.stopped = false;
+        /** The context's `samurai-toolbar` sandbox realms, as last listed: the only realms toolbar messages are taken from */
+        this.toolbarRealms = new Set();
+        /** Toolbar messages waiting for a realm lookup, and those that arrived behind them (kept in order) */
+        this.toolbarBacklog = Promise.resolve();
+        this.toolbarWaiting = 0;
+        /**
+         * Page messages come only on the capture channel; toolbar messages only on the toolbar channel and
+         * only from the toolbar's sandbox realm. Neither channel is reachable from page script (each stays in
+         * its script's closure, and the toolbar's in a sandbox the page cannot see); the realm check also
+         * holds if a page realm ever got the toolbar's channel.
+         */
         this.onMessage = (params) => {
-            if (params.channel !== this.channel ||
-                params.source.context !== this.context)
+            if (params.source.context !== this.context)
                 return;
-            const message = fromRemoteValue(params.data);
-            this.enqueue(async () => this.handle(message));
+            if (params.channel === this.channel) {
+                const message = fromRemoteValue(params.data);
+                if (message.type !== "toolbar")
+                    this.enqueue(async () => this.handle(message));
+                return;
+            }
+            if (params.channel !== this.toolbarChannel || !this.controller)
+                return;
+            const realm = params.source.realm ?? "";
+            if (this.toolbarWaiting === 0 && this.toolbarRealms.has(realm)) {
+                this.fromToolbar(params.data);
+                return;
+            }
+            // A sandbox not seen yet (a new document's toolbar): look it up, and keep later messages behind it
+            this.toolbarWaiting++;
+            this.toolbarBacklog = this.toolbarBacklog
+                .then(async () => {
+                if (!this.toolbarRealms.has(realm))
+                    await this.listToolbarRealms();
+                if (this.toolbarRealms.has(realm))
+                    this.fromToolbar(params.data);
+                else
+                    logger.warn("Recorder ignored a toolbar message from outside the toolbar's sandbox");
+            })
+                .catch((err) => {
+                logger.debug("Could not check a toolbar message's realm", { err });
+            })
+                .finally(() => this.toolbarWaiting--);
+        };
+        this.onLoad = (params) => {
+            if (params.context === this.context && params.url !== "about:blank")
+                this.controller?.loaded();
         };
         this.onNavigation = (params) => {
             if (params.context !== this.context || params.url === "about:blank")
                 return;
+            this.controller?.navigating();
             this.known.clear();
-            this.enqueue(async () => this.emit(this.normaliser.navigated(params.url, Date.now())));
+            this.enqueue(async () => {
+                // Paused: navigations are not recorded either
+                if (this.controller?.paused)
+                    return;
+                this.emit(this.normaliser.navigated(params.url, Date.now()));
+            });
         };
     }
     static async start(target, options) {
@@ -42,17 +102,49 @@ export class Recorder {
             at,
             ...(options.baseURL !== undefined && { baseURL: options.baseURL }),
         });
-        const recorder = new Recorder(target.page, target.connector, target.context, normaliser, options, `samurai-recorder-${randomUUID()}`);
+        const recorder = new Recorder(target.page, target.connector, target.context, normaliser, options, 
+        // The connector's debug log leaves out the data of these channels' messages (it knows them by prefix)
+        `samurai-recorder-${randomUUID()}`, `samurai-toolbar-${randomUUID()}`);
         await recorder.begin(options.initialGoto ?? true);
         return recorder;
     }
+    async listToolbarRealms() {
+        const { realms } = await this.connector.send("script.getRealms", {
+            context: this.context,
+            type: "window",
+        });
+        this.toolbarRealms = new Set(realms
+            .filter((info) => info.type === "window" && info.sandbox === TOOLBAR_SANDBOX)
+            .map((info) => info.realm));
+    }
+    /** A message from the toolbar's own sandbox */
+    fromToolbar(data) {
+        const message = fromRemoteValue(data);
+        const controller = this.controller;
+        if (!controller || message.type !== "toolbar" || !("action" in message))
+            return;
+        if (message.action === "ready") {
+            // Not behind a slow insert: the ready watchdog is waiting for it
+            void controller.handle(message);
+        }
+        else if (controller.accept(message)) {
+            // Decided as it arrives: a double click's second copy would only run after the first had finished
+            this.enqueue(async () => controller.handle(message));
+        }
+    }
     async begin(initialGoto) {
+        const toolbar = this.options.toolbar;
+        if (toolbar)
+            this.controller = this.createController(toolbar);
         this.connector.onEvent("script.message", this.onMessage);
         this.connector.onEvent("browsingContext.navigationStarted", this.onNavigation);
+        if (toolbar)
+            this.connector.onEvent("browsingContext.load", this.onLoad);
         try {
             this.subscription = await this.connector.subscribe([
                 "script.message",
                 "browsingContext.navigationStarted",
+                ...(toolbar ? ["browsingContext.load"] : []),
             ]);
             if (initialGoto) {
                 const url = await this.page.url();
@@ -65,12 +157,62 @@ export class Recorder {
                 arguments: [new ChannelArg(this.channel)],
                 onRunError: "log",
             });
+            if (this.controller) {
+                this.toolbarPreload = await addPreload(this.connector, {
+                    source: TOOLBAR_SOURCE,
+                    sandbox: TOOLBAR_SANDBOX,
+                    contexts: [this.context],
+                    arguments: [new ChannelArg(this.toolbarChannel)],
+                    onRunError: "log",
+                });
+                // The document that is loaded now gets its state and its ready watchdog as a new one would
+                this.controller.loaded();
+            }
         }
         catch (err) {
+            this.controller?.dispose();
             await this.release();
             throw err;
         }
     }
+    createController(toolbar) {
+        const { projectDir, environment, onStatus, onStop, onSecretAdded } = toolbar;
+        return new ToolbarController({
+            push: (state) => this.callToolbar("update", [state]),
+            reply: (id, result) => this.callToolbar("reply", [id, result]),
+            currentUrl: () => this.page.url(),
+            rank: (target, candidates) => rankLocator(this.page, target, candidates),
+            inspect: (target, locator, candidates) => inspectElement(this.page, this.connector, this.context, target, locator, candidates),
+            type: async (locator, value) => {
+                await this.mute();
+                try {
+                    await locatorFromSpec(this.page, locator).fill(value, {
+                        timeout: 5000,
+                    });
+                }
+                finally {
+                    await this.unmute();
+                }
+            },
+            mute: () => this.mute(),
+            unmute: () => this.unmute(),
+            addVariable: (name, value) => addVariable(projectDir, environment, name, value),
+            setSecret: (name, value) => setSecret(projectDir, environment, name, value),
+            secretAdded: (name) => onSecretAdded?.(name),
+            observe: (observation) => this.emit(this.normaliser.observe(observation, Date.now())),
+            stop: () => {
+                if (onStop)
+                    onStop();
+                else
+                    void this.stop();
+            },
+            onStatus: (status) => onStatus?.(status),
+        }, toolbar);
+    }
+    /** Calls the toolbar hook's `method` in the loaded document; a document between loads has no toolbar yet */
+    callToolbar(method, args) {
+        callFunction(this.connector, this.context, `(...args) => { ${HOOK}?.${method}(...args); }`, args, { sandbox: TOOLBAR_SANDBOX, awaitPromise: false }).catch((err) => logger.debug("Could not reach the recorder toolbar", { err }));
+    }
     enqueue(work) {
         this.queue.tail = this.queue.tail.then(work).catch((err) => {
             logger.warn("Recorder could not process an event", { err });
@@ -79,8 +221,11 @@ export class Recorder {
     emit(events) {
         if (this.stopped)
             return;
-        for (const event of events)
+        for (const event of events) {
             this.options.onEvent(event);
+            if (event.op === "insert")
+                this.controller?.stepAdded(event.step);
+        }
     }
     async locatorFor(message) {
         const { sharedId } = message.target;
@@ -91,6 +236,9 @@ export class Recorder {
         return spec;
     }
     async handle(message) {
+        // Paused: what the capture script still reports (before a new document is muted) is dropped
+        if (this.controller?.paused)
+            return;
         const locator = await this.locatorFor(message);
         if (!locator) {
             logger.warn("Recorder found no locator that matches only the element the tester used; the %s was skipped", message.type);
@@ -124,20 +272,57 @@ export class Recorder {
     async release() {
         this.connector.offEvent("script.message", this.onMessage);
         this.connector.offEvent("browsingContext.navigationStarted", this.onNavigation);
+        this.connector.offEvent("browsingContext.load", this.onLoad);
         await Promise.allSettled([
             this.subscription?.unsubscribe(),
             this.preload?.dispose(),
+            this.toolbarPreload?.dispose(),
         ]);
     }
+    /**
+     * Pauses capture in the loaded document: clicks and typing are not reported until `unmute`.
+     * @internal
+     */
+    async mute() {
+        await this.setMuted(CAPTURE_MUTE);
+    }
+    /** @internal */
+    async unmute() {
+        await this.setMuted(CAPTURE_UNMUTE);
+    }
+    async setMuted(source) {
+        await runInLoadedContexts(this.connector, {
+            source,
+            contexts: [this.context],
+            onRunError: "log",
+        });
+    }
     /** Stops recording. Events already received are still processed and reported first */
-    async stop() {
+    stop() {
+        this.stopping ??= this.end();
+        return this.stopping;
+    }
+    async end() {
         if (this.stopped)
             return;
+        this.controller?.dispose();
         await runInLoadedContexts(this.connector, {
             source: CAPTURE_OFF,
             contexts: [this.context],
             onRunError: "log",
         }).catch(() => undefined);
+        // A later recording of this document must not start muted
+        if (this.controller?.paused)
+            await this.unmute().catch(() => undefined);
+        if (this.toolbarPreload) {
+            // The window may stay open: take the toolbar and its listeners off the page
+            await runInLoadedContexts(this.connector, {
+                source: `() => { ${HOOK}?.dispose(); }`,
+                contexts: [this.context],
+                sandbox: TOOLBAR_SANDBOX,
+                onRunError: "log",
+            }).catch(() => undefined);
+        }
         await this.queue.tail;
         this.stopped = true;
         await this.release();

package/dist/recorder/session.d.ts

@@ -1,6 +1,9 @@
 import { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
+import type { PreparedRun } from "../runner/prepare-run.js";
 import { type ProjectOptions } from "../runner/project.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { ControllerOptions } from "./toolbar/controller.js";
 import type { RecorderEvent } from "./normalise.js";
 export interface RecordSpecOptions extends ProjectOptions {
     /** The spec file, absolute or relative to the project folder. Created when `create` is given and it doesn't exist */
@@ -24,6 +27,14 @@ export interface RecordSpecOptions extends ProjectOptions {
     signal?: AbortSignal;
     /** Called after each step is written to the file, with the file's new content */
     onEvent?: (event: RecorderEvent, source: string) => void;
+    /**
+     * 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?: (status: {
+        state: "recording" | "paused";
+        toolbar: boolean;
+    }) => void;
     /** Called once the browser is open and recording */
     onStarted?: (context: {
         page: Page;
@@ -38,6 +49,10 @@ export interface RecordResult {
     /** Names the recorded steps read with `secrets.<NAME>`: they must be set before the test can run */
     secrets: string[];
 }
+/** What the toolbar shows of the project: its environment, variables, secrets and the test's screenshots */
+export declare function toolbarOptions(run: Pick<PreparedRun, "settings" | "secrets">, source: string, dir: string, config: Pick<SamuraiTestConfig, "environments">, testIndex: number): Promise<ControllerOptions>;
+/** The secrets a recording needs set: those its steps read, then those added from the panel, once each */
+export declare function resultSecrets(events: readonly Pick<RecorderEvent, "step">[], added: Iterable<string>): string[];
 /** The index of the test `selector` names (see `RecordSpecOptions.test`) */
 export declare function pickTest(tests: readonly {
     name: string;

package/dist/recorder/session.js

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Browser } from "../browser/browser.js";
-import { projectDir } from "../config/config.js";
+import { ensureWarm } from "../browser/warm-up.js";
+import { loadConfig, projectDir } from "../config/config.js";
+import { isGitIgnored } from "../project/index.js";
 import { withProject } from "../runner/project.js";
 import { parseSpec } from "../steps/parse.js";
 import { applyRecorderEvent } from "./apply.js";
@@ -12,6 +14,47 @@ function addTest(source, title) {
         : `${source.replace(/\s*$/, "")}\n\n`;
     return `${header}test(${JSON.stringify(title)}, async ({ page }) => {\n});\n`;
 }
+/** Every `secrets.<NAME>` a parsed value contains, at any depth */
+function secretNames(node, found) {
+    if (Array.isArray(node))
+        node.forEach((item) => secretNames(item, found));
+    else if (node !== null && typeof node === "object") {
+        const record = node;
+        if (record.kind === "secret" && typeof record.name === "string")
+            found.add(record.name);
+        Object.values(record).forEach((item) => secretNames(item, found));
+    }
+}
+/** What the toolbar shows of the project: its environment, variables, secrets and the test's screenshots */
+export async function toolbarOptions(run, source, dir, config, testIndex) {
+    const tests = parseSpec(source);
+    const names = new Set(run.secrets.keys());
+    secretNames(tests, names);
+    const secrets = {};
+    for (const name of names)
+        secrets[name] = run.secrets.get(name);
+    const { environment } = run.settings;
+    return {
+        environment,
+        canAddVariables: typeof config.environments === "object",
+        variables: run.settings.variables,
+        secrets,
+        secretsIgnored: await isGitIgnored(dir, `.env.${environment}`),
+        screenshots: tests[testIndex]?.steps.filter(({ step }) => step.kind === "screenshot")
+            .length ?? 0,
+    };
+}
+/** The secrets a recording needs set: those its steps read, then those added from the panel, once each */
+export function resultSecrets(events, added) {
+    return [
+        ...new Set([
+            ...events.flatMap(({ step }) => step.kind === "fill" && step.value.kind === "secret"
+                ? [step.value.name]
+                : []),
+            ...added,
+        ]),
+    ];
+}
 /** The index of the test `selector` names (see `RecordSpecOptions.test`) */
 export function pickTest(tests, selector) {
     if (tests.length === 0)
@@ -46,12 +89,16 @@ export function pickTest(tests, selector) {
  *  await recordSpec({ file: "tests/login.spec.ts", create: "signs in", environment: "staging" });
  */
 export async function recordSpec(options) {
-    return withProject(options, async ({ settings }) => {
+    return withProject(options, async (run) => {
+        const { settings } = run;
         const file = path.resolve(projectDir(), options.file);
         let source = existsSync(file) ? readFileSync(file, "utf8") : undefined;
         if (source === undefined && options.create === undefined) {
             throw new Error(`${options.file} does not exist; give a title with --new to create it`);
         }
+        // Before the spec is touched: a recording without its browser changes nothing
+        await ensureWarm("firefox", { port: options.port ?? 9223 }, options.signal);
+        options.signal?.throwIfAborted();
         source ??= "";
         if (options.create !== undefined &&
             !parseSpec(source).some((t) => t.name === options.create)) {
@@ -71,6 +118,9 @@ export async function recordSpec(options) {
             headless: options.headless ?? settings.headless,
         }, options.signal);
         const events = [];
+        const addedSecrets = new Set();
+        let stopRequested;
+        const stopped = new Promise((resolve) => (stopRequested = resolve));
         try {
             const start = options.url ?? settings.baseURL;
             if (options.url !== undefined)
@@ -81,6 +131,13 @@ export async function recordSpec(options) {
                 at,
                 initialGoto: at === 0 && start !== undefined,
                 ...(settings.baseURL !== undefined && { baseURL: settings.baseURL }),
+                toolbar: {
+                    ...(await toolbarOptions(run, source, projectDir(), await loadConfig(), testIndex)),
+                    projectDir: projectDir(),
+                    ...(options.onStatus && { onStatus: options.onStatus }),
+                    onSecretAdded: (name) => addedSecrets.add(name),
+                    onStop: () => stopRequested(),
+                },
                 onEvent: (event) => {
                     source = applyRecorderEvent(source, testIndex, event);
                     writeFileSync(file, source);
@@ -98,6 +155,7 @@ export async function recordSpec(options) {
                     once: true,
                 });
                 void browser.exited.then(resolve);
+                void stopped.then(resolve);
             });
             // With the window gone there is nothing to ask: what was reported before is in the file
             if (!windowClosed)
@@ -106,11 +164,7 @@ export async function recordSpec(options) {
         finally {
             await browser.close().catch(() => undefined);
         }
-        const secrets = [
-            ...new Set(events.flatMap(({ step }) => step.kind === "fill" && step.value.kind === "secret"
-                ? [step.value.name]
-                : [])),
-        ];
+        const secrets = resultSecrets(events, addedSecrets);
         return { file, test: test.name, events, secrets };
     });
 }

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

@@ -0,0 +1,136 @@
+import type { ElementHandle } from "../../script/element-handle.js";
+import type { LocatorCall, LocatorSpec, Step } from "../../steps/model.js";
+import { type Observation } from "../normalise.js";
+import type { ActionReply, 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 & {
+        ok: true;
+    };
+    /** `counts[i]` is the locator `info.counts[i]` describes */
+    counts: LocatorCall[];
+}
+/** Everything the controller does to the browser and the project; the recorder implements these */
+export interface ControllerDeps {
+    /** Sends the state to every loaded top-level document's toolbar */
+    push(state: ToolbarState): void;
+    reply(id: number, result: PickInfo | ActionReply): void;
+    currentUrl(): Promise<string>;
+    rank(target: ElementHandle, candidates: LocatorCall[]): Promise<LocatorSpec | undefined>;
+    inspect(target: ElementHandle, locator: LocatorSpec, candidates: LocatorCall[]): Promise<Inspection>;
+    /** Types into the field with capture muted */
+    type(locator: LocatorSpec, value: string): Promise<void>;
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+    addVariable(name: string, value: string): Promise<void>;
+    setSecret(name: string, value: string): Promise<void>;
+    /** A secret was written to the project (called before its value is typed) */
+    secretAdded(name: string): void;
+    observe(observation: Observation): void;
+    stop(): void;
+    onStatus(status: {
+        state: "recording" | "paused";
+        toolbar: boolean;
+    }): void;
+}
+export interface ControllerOptions {
+    environment: string;
+    canAddVariables: boolean;
+    variables: Record<string, string | number | boolean>;
+    /** Name → value; undefined when not set */
+    secrets: Record<string, string | undefined>;
+    secretsIgnored: boolean;
+    /** Screenshot steps already in the test, for the default name */
+    screenshots: number;
+}
+type Message = ToolbarMessage & {
+    target?: ElementHandle;
+};
+/**
+ * The recorder's side of the toolbar: owns its state (pause, the rail, the environment's variables and
+ * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
+ * their names and whether they are set.
+ */
+export declare class ToolbarController {
+    private readonly deps;
+    private readonly options;
+    private status;
+    private collapsed;
+    private position;
+    private steps;
+    private screenshots;
+    private readonly variables;
+    private readonly secrets;
+    private pausedAt;
+    /** The URL the resume question offers; set while it is asked */
+    private question;
+    private toast;
+    private toastId;
+    /** The picked element an `assert` with the same id refers to */
+    private pick;
+    /** Ids of `assert`, `insert` and `add-insertable` being processed */
+    private readonly inFlight;
+    /** Ids `accept` let through whose `handle` hasn't started yet */
+    private readonly claimed;
+    /** Ids answered `{ ok: true }`: their step exists, a repeat is a double click */
+    private readonly done;
+    /** Bumped on every page load: work started for an older page is not answered */
+    private page;
+    private toolbar;
+    /** A `ready` arrived since the last load: it counts for the next one */
+    private readySinceLoad;
+    private watchdog;
+    private disposed;
+    constructor(deps: ControllerDeps, options: ControllerOptions);
+    get paused(): boolean;
+    private state;
+    private push;
+    private reply;
+    private reportStatus;
+    private setToolbar;
+    private showToast;
+    handle(message: Message): Promise<void>;
+    /** A top-level document finished loading: push state; start the 2 s ready watchdog */
+    loaded(): void;
+    /**
+     * A top-level navigation to a new document started: a `ready` from before it belongs to the old document
+     * and doesn't count for the coming load
+     */
+    navigating(): void;
+    /** A step was emitted (any source): count it */
+    stepAdded(step: Step): void;
+    /** The recording ended: no more pushes, replies or status */
+    dispose(): void;
+    /**
+     * The toolbar draws at document start, so its `ready` usually comes before the load; Firefox also runs it
+     * in a transient about:blank while navigating. A `ready` that arrives while the watchdog runs settles it;
+     * any other counts for the next load.
+     */
+    private ready;
+    private pause;
+    private resume;
+    private answer;
+    /** Runs an action that expects a reply; a second one with the same id while the first runs is dropped */
+    /**
+     * Whether to process `message`; call it as the message arrives, before queueing it. An `assert`, `insert` or
+     * `add-insertable` whose id is in flight or was already answered `{ ok: true }` is a double click and is
+     * dropped (its first copy answers). A retry after `{ ok: false }` is accepted.
+     */
+    accept(message: Message): boolean;
+    /** Runs an action that expects a reply, unless it is a repeat (see `accept`) */
+    private once;
+    private picked;
+    /**
+     * A field may hold an inserted secret: its value (and any text or attribute equal to a secret) is left out,
+     * and the first matcher follows the Alt+click rule without a value, so neither the page nor the spec gets it.
+     */
+    private withoutSecrets;
+    private assert;
+    private insert;
+    private addInsertable;
+    /** Undefined when `work` succeeded, else the reply for its error */
+    private write;
+    private locate;
+    private typeIn;
+}
+export {};