@itmetsam/samurai-framework 0.10.0 → 0.12.0

package/dist/recorder/recorder.js

@@ -1,26 +1,19 @@
 import { randomUUID } from "node:crypto";
-import { mkdtemp, open, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
 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 { locatorFromSpec } from "../steps/build.js";
-import { addVariable, cleanFileName, filesFolder, RECORD_LIMIT, setSecret, storeFile, } from "../project/index.js";
-import { humanSize } from "../steps/files.js";
 import { CAPTURE_MUTE, CAPTURE_OFF, CAPTURE_SOURCE, CAPTURE_UNMUTE, } from "./capture.js";
 import { FILES_SANDBOX, filesCaptureSource } from "./files-capture.js";
-import { disposeFilesCapture, readPageFile, releasePageFile, } from "./files-reader.js";
-import { Normaliser, } from "./normalise.js";
+import { disposeFilesCapture, releasePageFile } from "./files-reader.js";
+import { FilesRecorder, missingFileText } from "./files-recorder.js";
+import { Normaliser } from "./normalise.js";
+import { observationFor, } from "./page-messages.js";
+import { listSandboxRealms } from "./realms.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_HOOK, ToolbarBridge } from "./toolbar-bridge.js";
+import { 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)})]`;
+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
@@ -47,13 +40,6 @@ export class Recorder {
         /** The files capture script's channel, handed only to its sandbox */
         this.filesChannel = `samurai-files-${randomUUID()}`;
         this.filesRealms = new Set();
-        this.stored = new Set();
-        this.missing = [];
-        /** 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
@@ -86,28 +72,9 @@ export class Recorder {
                 });
                 return;
             }
-            if (params.channel !== this.toolbarChannel || !this.controller)
+            if (params.channel !== this.toolbarChannel || !this.toolbar)
                 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.toolbar.receive(params.source.realm ?? "", params.data);
         };
         this.onLoad = (params) => {
             if (params.context === this.context && params.url !== "about:blank")
@@ -126,13 +93,17 @@ export class Recorder {
             });
         };
     }
+    /** The toolbar's controller, when the recording has a toolbar */
+    get controller() {
+        return this.toolbar?.controller;
+    }
     /** Files stored or reused in the files folder by this recording, project-relative */
     get storedFiles() {
-        return [...this.stored];
+        return this.files?.storedFiles ?? [];
     }
     /** Files whose steps point at a path that wasn't written */
     get missingFiles() {
-        return [...this.missing];
+        return this.files?.missingFiles ?? [];
     }
     static async start(target, options) {
         const at = options.at ?? 0;
@@ -147,42 +118,13 @@ export class Recorder {
         return recorder;
     }
     async listFilesRealms() {
-        const { realms } = await this.connector.send("script.getRealms", {
-            context: this.context,
-            type: "window",
-        });
-        this.filesRealms = new Set(realms
-            .filter((info) => info.type === "window" && info.sandbox === FILES_SANDBOX)
-            .map((info) => info.realm));
-    }
-    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));
-        }
+        this.filesRealms = await listSandboxRealms(this.connector, this.context, FILES_SANDBOX);
     }
     async begin(initialGoto) {
         const toolbar = this.options.toolbar;
         if (toolbar)
-            this.controller = this.createController(toolbar);
+            this.toolbar = this.createToolbar(toolbar);
+        this.files = this.createFiles();
         this.connector.onEvent("script.message", this.onMessage);
         this.connector.onEvent("browsingContext.navigationStarted", this.onNavigation);
         if (toolbar)
@@ -215,7 +157,7 @@ export class Recorder {
                     onRunError: "log",
                 });
             }
-            if (this.controller) {
+            if (this.toolbar) {
                 this.toolbarPreload = await addPreload(this.connector, {
                     source: TOOLBAR_SOURCE,
                     sandbox: TOOLBAR_SANDBOX,
@@ -224,7 +166,7 @@ export class Recorder {
                     onRunError: "log",
                 });
                 // The document that is loaded now gets its state and its ready watchdog as a new one would
-                this.controller.loaded();
+                this.toolbar.controller.loaded();
             }
         }
         catch (err) {
@@ -233,43 +175,26 @@ export class Recorder {
             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();
-                }
-            },
+    createToolbar(toolbar) {
+        return new ToolbarBridge({
+            page: this.page,
+            connector: this.connector,
+            context: this.context,
             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),
+            stop: () => void this.stop(),
+            enqueue: (work) => this.enqueue(work),
         }, 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 }));
+    createFiles() {
+        const recording = this.options.files;
+        if (!recording)
+            return undefined;
+        return new FilesRecorder(this.connector, this.context, recording, {
+            warn: (text) => this.controller?.warn(text),
+            saving: (name) => this.controller?.saving(name),
+        });
     }
     enqueue(work) {
         this.queue.tail = this.queue.tail.then(work).catch((err) => {
@@ -304,29 +229,7 @@ export class Recorder {
             logger.warn("Recorder found no locator that matches only the element the tester used; the %s was skipped", message.type);
             return;
         }
-        const key = message.target.sharedId;
-        const observation = 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,
-                        }),
-                    };
+        const observation = observationFor(message, locator);
         this.emit(this.normaliser.observe(observation, Date.now()));
     }
     async fromFiles(message) {
@@ -352,7 +255,7 @@ export class Recorder {
             const files = [];
             for (const file of message.files) {
                 started++;
-                files.push({ path: await this.storePageFile(file) });
+                files.push({ path: await this.files.store(file) });
             }
             this.emit(this.normaliser.observe({ type: "files", via: message.via, locator, files }, now));
         }
@@ -360,62 +263,6 @@ export class Recorder {
             await release(started);
         }
     }
-    /** Saves one kept file to the files folder; returns the path its step gets */
-    async storePageFile(file) {
-        const recording = this.options.files;
-        const folder = filesFolder(recording.projectDir, recording.filesDir);
-        const notSaved = (reason) => {
-            const missing = {
-                path: folder.relative
-                    ? `${folder.relative}/${cleanFileName(file.name)}`
-                    : cleanFileName(file.name),
-                name: file.name,
-                size: file.size,
-                reason,
-            };
-            this.missing.push(missing);
-            recording.onMissing?.(missing);
-            this.controller?.warn(missingFileText(missing, folder.relative));
-            return missing.path;
-        };
-        if (file.size > RECORD_LIMIT) {
-            await releasePageFile(this.connector, this.context, file.id).catch(() => undefined);
-            return notSaved("too-big");
-        }
-        this.controller?.saving(file.name);
-        let temp;
-        try {
-            temp = await mkdtemp(path.join(tmpdir(), "samurai-upload-"));
-            const content = path.join(temp, "content");
-            const out = await open(content, "w");
-            try {
-                await readPageFile(this.connector, this.context, file.id, file.size, (bytes) => out.write(bytes));
-            }
-            finally {
-                await out.close();
-            }
-            const stored = await storeFile({
-                projectDir: recording.projectDir,
-                ...(recording.filesDir !== undefined && {
-                    filesDir: recording.filesDir,
-                }),
-                name: file.name,
-                content,
-            });
-            this.stored.add(stored.path);
-            return stored.path;
-        }
-        catch (err) {
-            logger.warn("Recorder could not save %s", file.name, { err });
-            return notSaved("unreadable");
-        }
-        finally {
-            this.controller?.saving(undefined);
-            if (temp)
-                await rm(temp, { recursive: true, force: true }).catch(() => undefined);
-            await releasePageFile(this.connector, this.context, file.id).catch(() => undefined);
-        }
-    }
     async release() {
         this.connector.offEvent("script.message", this.onMessage);
         this.connector.offEvent("browsingContext.navigationStarted", this.onNavigation);
@@ -466,7 +313,7 @@ export class Recorder {
         if (this.toolbarPreload) {
             // The window may stay open: take the toolbar and its listeners off the page
             await runInLoadedContexts(this.connector, {
-                source: `() => { ${HOOK}?.dispose(); }`,
+                source: `() => { ${TOOLBAR_HOOK}?.dispose(); }`,
                 contexts: [this.context],
                 sandbox: TOOLBAR_SANDBOX,
                 onRunError: "log",
@@ -480,10 +327,3 @@ export class Recorder {
         await this.release();
     }
 }
-/** The warning for a file that isn't saved, as the toolbar and the CLI show it */
-export function missingFileText(file, folder) {
-    const where = folder === "" ? "the project folder" : `${folder}/`;
-    return file.reason === "too-big"
-        ? `${file.name} is ${humanSize(file.size)}. Files over 50 MB aren't saved: add it to ${where} yourself, or use a generated file.`
-        : `${file.name} couldn't be read, so it isn't saved: add it to ${where} yourself, or use a generated file.`;
-}

package/dist/recorder/session-browser.d.ts

@@ -0,0 +1,22 @@
+import { Browser } from "../browser/browser.js";
+import type Page from "../browser/page.js";
+import type { SupportedBrowser } from "../types/browser.js";
+interface BrowserChoice {
+    browser?: SupportedBrowser | undefined;
+    port?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * The browser a recording uses: the one asked for, else the first of the project's (recording in two browsers at
+ * once makes no sense). A fresh build is started once first, so a missing browser or a slow first start stops
+ * the recording before the spec is touched.
+ */
+export declare function prepareRecordingBrowser(options: BrowserChoice): Promise<SupportedBrowser>;
+/** Opens the browser of `prepareRecordingBrowser` */
+export declare function launchRecordingBrowser(name: SupportedBrowser, options: BrowserChoice & {
+    headless: boolean;
+}): Promise<{
+    browser: Browser;
+    page: Page;
+}>;
+export {};

package/dist/recorder/session-browser.js

@@ -0,0 +1,21 @@
+import { Browser } from "../browser/browser.js";
+import { ensureWarm } from "../browser/warm-up.js";
+import { readConfig } from "../config/config.js";
+import { browsersFor } from "../runner/browsers.js";
+import { DEFAULT_PORT } from "../runner/ports.js";
+/**
+ * The browser a recording uses: the one asked for, else the first of the project's (recording in two browsers at
+ * once makes no sense). A fresh build is started once first, so a missing browser or a slow first start stops
+ * the recording before the spec is touched.
+ */
+export async function prepareRecordingBrowser(options) {
+    const name = options.browser ??
+        browsersFor({ project: await readConfig("browsers") })[0];
+    await ensureWarm(name, { port: options.port ?? DEFAULT_PORT }, options.signal);
+    options.signal?.throwIfAborted();
+    return name;
+}
+/** Opens the browser of `prepareRecordingBrowser` */
+export function launchRecordingBrowser(name, options) {
+    return Browser.launch(name, { port: options.port ?? DEFAULT_PORT, headless: options.headless }, options.signal);
+}

package/dist/recorder/session-secrets.d.ts

@@ -0,0 +1,8 @@
+import type { PreparedRun } from "../runner/prepare-run.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { RecorderEvent } from "./normalise.js";
+import type { ControllerOptions } from "./toolbar/types.js";
+/** 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 RecorderEvent[], added: Iterable<string>): string[];

package/dist/recorder/session-secrets.js

@@ -0,0 +1,45 @@
+import { isGitIgnored } from "../project/index.js";
+import { parseSpec } from "../steps/parse.js";
+/** 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((event) => event.op !== "remove" &&
+                event.step.kind === "fill" &&
+                event.step.value.kind === "secret"
+                ? [event.step.value.name]
+                : []),
+            ...added,
+        ]),
+    ];
+}

package/dist/recorder/session.d.ts

@@ -1,12 +1,11 @@
-import { Browser } from "../browser/browser.js";
+import type { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
-import type { SupportedBrowser } from "../types/browser.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 { SupportedBrowser } from "../types/browser.js";
 import type { RecorderEvent } from "./normalise.js";
 import { type MissingFile } from "./recorder.js";
+export { pickTest } from "./spec-source.js";
+export { resultSecrets, toolbarOptions } from "./session-secrets.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 */
     file: string;
@@ -23,7 +22,7 @@ export interface RecordSpecOptions extends ProjectOptions {
     url?: string;
     /** The browser to record in. @default the first of the config's `browsers`, else Firefox */
     browser?: SupportedBrowser;
-    /** The browser's debugging port. @default 9223 */
+    /** The browser's debugging port. @default DEFAULT_PORT (9223) */
     port?: number;
     /** Run the browser without a window. A person can't use it then; for tests and machines without a display. @default the config's `use.headless`, else headless on CI and a window otherwise */
     headless?: boolean;
@@ -67,14 +66,6 @@ export interface RecordResult {
     /** The files folder was created by this recording */
     firstFiles: boolean;
 }
-/** 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 RecorderEvent[], added: Iterable<string>): string[];
-/** The index of the test `selector` names (see `RecordSpecOptions.test`) */
-export declare function pickTest(tests: readonly {
-    name: string;
-}[], selector: string | number | undefined): number;
 /**
  * Opens a browser window and records what the person does into a spec file, step by step, until `signal`
  * aborts or the window is closed. Every step is written to the file as it happens, as a minimal edit.