@itmetsam/samurai-framework 0.6.0 → 0.7.1

package/dist/recorder/toolbar/controller.js

@@ -0,0 +1,471 @@
+import { cleanName } from "../../browser/evidence.js";
+import { ConfigEditError } from "../../project/config-edit.js";
+import { SECRET_NAME } from "../../project/secrets-file.js";
+import { ExistsError, VARIABLE_NAME } from "../../project/variables.js";
+import { expectationFor } from "../normalise.js";
+/** A wait for time is 0.1–60 s */
+const WAIT_MIN_MS = 100;
+const WAIT_MAX_MS = 60000;
+/** How long a loaded page's toolbar has to say `ready` */
+const READY_WITHIN = 2000;
+const UNIDENTIFIABLE = "This element can't be identified uniquely";
+const TYPE_FAILED = "Couldn't type into that field";
+const NO_ENVIRONMENT = "This recording has no environment";
+const PAUSED = "Nothing you do now is recorded.";
+const fail = (error, field) => ({
+    ok: false,
+    error,
+    ...(field && { field }),
+});
+/**
+ * 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 class ToolbarController {
+    constructor(deps, options) {
+        this.deps = deps;
+        this.options = options;
+        this.status = "recording";
+        this.collapsed = false;
+        this.position = null;
+        this.steps = 0;
+        this.toastId = 0;
+        /** Ids of `assert`, `insert` and `add-insertable` being processed */
+        this.inFlight = new Set();
+        /** Ids `accept` let through whose `handle` hasn't started yet */
+        this.claimed = new Set();
+        /** Ids answered `{ ok: true }`: their step exists, a repeat is a double click */
+        this.done = new Set();
+        /** Bumped on every page load: work started for an older page is not answered */
+        this.page = 0;
+        this.toolbar = true;
+        /** A `ready` arrived since the last load: it counts for the next one */
+        this.readySinceLoad = false;
+        this.disposed = false;
+        this.screenshots = options.screenshots;
+        this.variables = new Map(Object.entries(options.variables).map(([name, value]) => [
+            name,
+            String(value),
+        ]));
+        this.secrets = new Map(Object.entries(options.secrets));
+    }
+    get paused() {
+        return this.status === "paused";
+    }
+    state() {
+        return {
+            status: this.status,
+            collapsed: this.collapsed,
+            position: this.position,
+            steps: this.steps,
+            environment: this.options.environment,
+            canAddVariables: this.options.canAddVariables,
+            variables: [...this.variables].map(([name, value]) => ({ name, value })),
+            secrets: [...this.secrets].map(([name, value]) => ({
+                name,
+                set: value !== undefined,
+            })),
+            secretsIgnored: this.options.secretsIgnored,
+            resumeQuestion: this.question !== undefined,
+            nextScreenshot: `screenshot-${this.screenshots + 1}`,
+            ...(this.toast && { toast: this.toast }),
+        };
+    }
+    push() {
+        if (!this.disposed)
+            this.deps.push(this.state());
+    }
+    reply(id, result) {
+        if (!this.disposed)
+            this.deps.reply(id, result);
+    }
+    reportStatus() {
+        if (!this.disposed)
+            this.deps.onStatus({ state: this.status, toolbar: this.toolbar });
+    }
+    setToolbar(loaded) {
+        if (this.toolbar === loaded)
+            return;
+        this.toolbar = loaded;
+        this.reportStatus();
+    }
+    showToast(text) {
+        this.toast = { id: ++this.toastId, text };
+    }
+    async handle(message) {
+        if (this.disposed)
+            return;
+        switch (message.action) {
+            case "ready":
+                return this.ready(message.url);
+            case "pause":
+                return this.pause();
+            case "resume":
+                return this.resume();
+            case "resume-goto":
+                return this.answer(message.add);
+            case "stop":
+                return this.deps.stop();
+            case "move":
+                if (!Number.isFinite(message.x) || !Number.isFinite(message.y))
+                    return;
+                this.position = { x: Math.round(message.x), y: Math.round(message.y) };
+                return this.push();
+            case "collapse":
+                this.collapsed = message.collapsed === true;
+                this.pick = undefined;
+                return this.push();
+            case "pick":
+                return this.picked(message);
+            case "assert":
+                return this.once(message, () => this.assert(message));
+            case "insert":
+                return this.once(message, () => this.insert(message));
+            case "add-insertable":
+                return this.once(message, () => this.addInsertable(message));
+            case "wait":
+                if (this.paused)
+                    return;
+                if (message.kind === "time") {
+                    if (!Number.isFinite(message.ms) || message.ms < 0)
+                        return;
+                    // The panel's range (0.1–60 s), whatever the message says
+                    const ms = Math.min(WAIT_MAX_MS, Math.max(WAIT_MIN_MS, Math.round(message.ms)));
+                    this.deps.observe({ type: "wait-time", ms });
+                }
+                else {
+                    this.deps.observe({ type: "wait-idle" });
+                }
+                this.showToast("Wait step added");
+                return this.push();
+            case "screenshot":
+                if (this.paused)
+                    return;
+                this.deps.observe({
+                    type: "screenshot",
+                    name: cleanName(String(message.name ?? "")),
+                    fullPage: message.fullPage === true,
+                });
+                this.showToast("Screenshot step added");
+                return this.push();
+        }
+    }
+    /** A top-level document finished loading: push state; start the 2 s ready watchdog */
+    loaded() {
+        if (this.disposed)
+            return;
+        this.page++;
+        this.pick = undefined;
+        this.toast = undefined;
+        this.push();
+        // A new document starts with capture on
+        if (this.paused)
+            void this.deps.mute().catch(() => undefined);
+        clearTimeout(this.watchdog);
+        this.watchdog = undefined;
+        if (this.readySinceLoad) {
+            this.readySinceLoad = false;
+            this.setToolbar(true);
+            return;
+        }
+        this.watchdog = setTimeout(() => {
+            this.watchdog = undefined;
+            this.setToolbar(false);
+        }, READY_WITHIN);
+    }
+    /**
+     * 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() {
+        this.readySinceLoad = false;
+    }
+    /** A step was emitted (any source): count it */
+    stepAdded(step) {
+        this.steps++;
+        if (step.kind === "screenshot")
+            this.screenshots++;
+        this.push();
+    }
+    /** The recording ended: no more pushes, replies or status */
+    dispose() {
+        this.disposed = true;
+        clearTimeout(this.watchdog);
+        this.watchdog = undefined;
+    }
+    /**
+     * 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.
+     */
+    ready(url) {
+        // The transient about:blank Firefox passes through while navigating is not the page being recorded
+        if (url === "about:blank")
+            return;
+        if (this.watchdog !== undefined) {
+            clearTimeout(this.watchdog);
+            this.watchdog = undefined;
+        }
+        else if (this.toolbar) {
+            this.readySinceLoad = true;
+        }
+        this.setToolbar(true);
+        this.push();
+    }
+    async pause() {
+        if (this.paused)
+            return;
+        this.status = "paused";
+        this.question = undefined;
+        this.pick = undefined;
+        this.push();
+        this.reportStatus();
+        const [, url] = await Promise.all([
+            this.deps.mute(),
+            this.deps.currentUrl(),
+        ]);
+        this.pausedAt = url;
+    }
+    async resume() {
+        if (!this.paused)
+            return;
+        const url = await this.deps.currentUrl();
+        await this.deps.unmute();
+        this.status = "recording";
+        this.question =
+            this.pausedAt !== undefined && url !== this.pausedAt ? url : undefined;
+        this.pausedAt = undefined;
+        this.push();
+        this.reportStatus();
+    }
+    answer(add) {
+        const url = this.question;
+        if (url === undefined)
+            return;
+        this.question = undefined;
+        if (add === true)
+            this.deps.observe({ type: "goto", url });
+        this.push();
+    }
+    /** 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) {
+        if (message.action !== "assert" &&
+            message.action !== "insert" &&
+            message.action !== "add-insertable")
+            return true;
+        const { id } = message;
+        if (this.inFlight.has(id) || this.done.has(id))
+            return false;
+        this.inFlight.add(id);
+        this.claimed.add(id);
+        return true;
+    }
+    /** Runs an action that expects a reply, unless it is a repeat (see `accept`) */
+    async once(message, work) {
+        const { id } = message;
+        if (!this.claimed.has(id) && !this.accept(message))
+            return;
+        this.claimed.delete(id);
+        try {
+            const result = await work();
+            if (result.ok)
+                this.done.add(id);
+            this.reply(id, result);
+        }
+        finally {
+            this.inFlight.delete(id);
+        }
+    }
+    async picked(message) {
+        const page = this.page;
+        if (this.paused)
+            return this.reply(message.id, fail(PAUSED));
+        let found;
+        try {
+            const locator = message.target &&
+                (await this.deps.rank(message.target, message.candidates));
+            if (locator) {
+                found = await this.deps.inspect(message.target, locator, message.candidates);
+                if (page === this.page)
+                    this.pick = { id: message.id, locator, counts: found.counts };
+            }
+        }
+        catch {
+            found = undefined; // the element went away while it was inspected
+        }
+        // The page that asked is gone: its successor's toolbar isn't waiting for this
+        if (page !== this.page)
+            return;
+        this.reply(message.id, found ? this.withoutSecrets(found.info) : fail(UNIDENTIFIABLE));
+    }
+    /**
+     * 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.
+     */
+    withoutSecrets(info) {
+        const values = [...this.secrets.values()].filter((value) => value !== undefined && value !== "");
+        const secret = (text) => text !== undefined && values.some((value) => text.includes(value));
+        if (!secret(info.value) &&
+            !secret(info.text) &&
+            !secret(info.first.expected) &&
+            !info.attributes.some((a) => secret(a.value)))
+            return info;
+        const text = secret(info.text) ? "" : info.text;
+        const first = expectationFor(text, undefined);
+        const { value: _value, ...rest } = info;
+        return {
+            ...rest,
+            text,
+            attributes: info.attributes.filter((a) => !secret(a.value)),
+            first: {
+                matcher: first.matcher,
+                ...("expected" in first && { expected: String(first.expected) }),
+            },
+        };
+    }
+    async assert(message) {
+        if (this.paused)
+            return fail(PAUSED);
+        const pick = this.pick;
+        if (!pick || pick.id !== message.id)
+            return fail("Pick the element again");
+        let locator = pick.locator;
+        let expectation;
+        const expected = String(message.expected ?? "");
+        switch (message.matcher) {
+            case "toBeVisible":
+                expectation = { matcher: "toBeVisible" };
+                break;
+            case "toHaveText":
+            case "toContainText":
+            case "toHaveValue":
+                expectation = { matcher: message.matcher, expected };
+                break;
+            case "toHaveAttribute":
+                if (!message.attribute)
+                    return fail("Choose an attribute");
+                expectation = {
+                    matcher: "toHaveAttribute",
+                    name: message.attribute,
+                    expected,
+                };
+                break;
+            case "toHaveCount": {
+                const call = pick.counts[message.countIndex ?? 0];
+                const count = Number(expected);
+                if (!call)
+                    return fail("Choose what to count");
+                if (expected.trim() === "" || !Number.isInteger(count) || count < 0)
+                    return fail("A count is a whole number");
+                locator = { chain: [call], fallbacks: [] };
+                expectation = { matcher: "toHaveCount", expected: count };
+                break;
+            }
+            default:
+                return fail("Choose a matcher");
+        }
+        this.pick = undefined;
+        this.deps.observe({
+            type: "expect",
+            locator,
+            not: message.not === true,
+            expectation,
+        });
+        return { ok: true };
+    }
+    async insert(message) {
+        if (this.paused)
+            return fail(PAUSED);
+        const { kind, name } = message;
+        const value = kind === "secret" ? this.secrets.get(name) : this.variables.get(name);
+        if (value === undefined)
+            return fail(kind === "secret"
+                ? `Set a value for ${name} first`
+                : `There is no variable "${name}"`);
+        const locator = await this.locate(message);
+        if (!locator)
+            return fail(UNIDENTIFIABLE);
+        return this.typeIn(locator, kind, name, value);
+    }
+    async addInsertable(message) {
+        if (this.paused)
+            return fail(PAUSED);
+        const { kind, name } = message;
+        const value = String(message.value ?? "");
+        if (kind === "env" && !this.options.canAddVariables)
+            return fail(NO_ENVIRONMENT);
+        const known = kind === "env"
+            ? this.variables.has(name)
+            : this.secrets.get(name) !== undefined;
+        if (known)
+            return fail(`"${name}" already exists`, "name");
+        // Found before anything is written: an element that can't be filled leaves the project as it was
+        const locator = await this.locate(message);
+        if (!locator)
+            return fail(UNIDENTIFIABLE);
+        const written = kind === "env"
+            ? await this.write(() => this.deps.addVariable(name, value), (err) => err instanceof ConfigEditError
+                ? fail(`samurai.config.ts can't be changed automatically. Add ${name} to environments.${this.options.environment}.variables yourself.`)
+                : err instanceof ExistsError || !VARIABLE_NAME.test(name)
+                    ? fail(errorText(err), "name")
+                    : fail(errorText(err)))
+            : await this.write(() => this.deps.setSecret(name, value), (err) => 
+            // An error never echoes the value
+            SECRET_NAME.test(name)
+                ? fail(scrub(errorText(err), value))
+                : fail(scrub(errorText(err), value), "name"));
+        if (written)
+            return written;
+        if (kind === "env")
+            this.variables.set(name, value);
+        else {
+            this.secrets.set(name, value);
+            this.deps.secretAdded(name);
+        }
+        this.push();
+        return this.typeIn(locator, kind, name, value, true);
+    }
+    /** Undefined when `work` succeeded, else the reply for its error */
+    async write(work, replyFor) {
+        try {
+            await work();
+            return undefined;
+        }
+        catch (err) {
+            return replyFor(err);
+        }
+    }
+    async locate(message) {
+        if (!message.target)
+            return undefined;
+        try {
+            return await this.deps.rank(message.target, message.candidates);
+        }
+        catch {
+            return undefined; // the element went away
+        }
+    }
+    async typeIn(locator, kind, name, value, saved = false) {
+        try {
+            await this.deps.type(locator, value);
+        }
+        catch {
+            // Typing clicks the field, which closes the panel the reply is for: the toast is what the tester sees
+            this.showToast(saved
+                ? `Saved ${name}, but couldn't type into that field`
+                : TYPE_FAILED);
+            this.push();
+            return fail(TYPE_FAILED);
+        }
+        this.deps.observe({ type: "insert", locator, value: { kind, name } });
+        return { ok: true };
+    }
+}
+const errorText = (err) => err instanceof Error ? err.message : String(err);
+const scrub = (text, secret) => secret === "" ? text : text.split(secret).join("••••••");

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

@@ -0,0 +1,12 @@
+import type Page from "../../browser/page.js";
+import type { ElementHandle } from "../../script/element-handle.js";
+import type { LocatorCall, LocatorSpec } from "../../steps/model.js";
+import type { BiDiConnector } from "../../transport/bidi-connection.js";
+import type { Inspection } from "./controller.js";
+/** A locator call in short, as the Assert panel shows it: `heading "Sign in"`, `label "Email"`, `li.item` */
+export declare function describeCall(call: LocatorCall): string;
+/**
+ * What the Assert panel needs for a picked element: its short label, text, value, attributes, the first
+ * matcher (today's Alt+click rule) and up to three locators that match more than one element, with counts.
+ */
+export declare function inspectElement(page: Page, connector: BiDiConnector, context: string, target: ElementHandle, locator: LocatorSpec, candidates: LocatorCall[]): Promise<Inspection>;

package/dist/recorder/toolbar/inspect.js

@@ -0,0 +1,94 @@
+import { callFunction } from "../../script/call-function.js";
+import { locatorFromSpec } from "../../steps/build.js";
+import { CANDIDATES_JS } from "../candidates.js";
+import { expectationFor } from "../normalise.js";
+import { TOOLBAR_SANDBOX } from "./protocol.js";
+/** Most Count choices the Assert panel offers */
+const MAX_COUNTS = 3;
+/**
+ * Run in the toolbar's sandbox on the picked element: its text (cut at 4 KB), value (as the Alt+click rule reads it), first
+ * 20 attributes, its role without a name and its `tag.class` selector. `roleOf` only knows the roles the
+ * candidates use, so the common list and table roles are added for Count.
+ */
+const INSPECT_SOURCE = String.raw `(el) => {
+  ${CANDIDATES_JS}
+  const TEXT_CAP = 4096;
+  const MORE_ROLES = { li: "listitem", ul: "list", ol: "list", tr: "row", td: "cell", th: "columnheader", option: "option", nav: "navigation", table: "table", article: "article", dialog: "dialog" };
+  const tag = el.tagName.toLowerCase();
+  const hasValue = typeof el.value === "string" && el.tagName !== "BUTTON" && el.tagName !== "LI";
+  const secret = tag === "input" && (el.getAttribute("type") || "").toLowerCase() === "password";
+  const classes = Array.from(el.classList).filter(Boolean);
+  return {
+    text: norm(String(el.textContent == null ? "" : el.textContent).slice(0, TEXT_CAP * 2)).slice(0, TEXT_CAP),
+    value: hasValue && !secret ? el.value : null,
+    attributes: Array.from(el.attributes).slice(0, 20).map((a) => ({ name: a.name, value: a.value })),
+    role: roleOf(el) || MORE_ROLES[tag] || null,
+    css: classes.length ? CSS.escape(tag) + classes.map((c) => "." + CSS.escape(c)).join("") : null,
+  };
+}`;
+/** A locator call in short, as the Assert panel shows it: `heading "Sign in"`, `label "Email"`, `li.item` */
+export function describeCall(call) {
+    switch (call.method) {
+        case "getByRole":
+            return call.name === undefined
+                ? call.role
+                : `${call.role} "${call.name}"`;
+        case "getByLabel":
+            return `label "${call.text}"`;
+        case "getByText":
+            return `text "${call.text}"`;
+        case "getByTestId":
+            return `test id "${call.testId}"`;
+        case "getByCss":
+            return call.css;
+        case "locator":
+            return call.xpath;
+    }
+}
+const sameCall = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * What the Assert panel needs for a picked element: its short label, text, value, attributes, the first
+ * matcher (today's Alt+click rule) and up to three locators that match more than one element, with counts.
+ */
+export async function inspectElement(page, connector, context, target, locator, candidates) {
+    const found = await callFunction(connector, context, INSPECT_SOURCE, [target], { sandbox: TOOLBAR_SANDBOX });
+    const value = found.value ?? undefined;
+    const first = expectationFor(found.text, value);
+    // The element's role without a name, its tag with its classes, then its other candidates
+    const options = [];
+    if (found.role)
+        options.push({ method: "getByRole", role: found.role });
+    if (found.css)
+        options.push({ method: "getByCss", css: found.css });
+    for (const call of candidates)
+        if (call.method !== "locator" && !options.some((o) => sameCall(o, call)))
+            options.push(call);
+    const calls = [];
+    const counts = [];
+    for (const call of options) {
+        if (calls.length >= MAX_COUNTS)
+            break;
+        const count = await locatorFromSpec(page, { chain: [call], fallbacks: [] })
+            .count()
+            .catch(() => 0); // e.g. a role the browser doesn't know
+        if (count <= 1)
+            continue;
+        calls.push(call);
+        counts.push({ label: describeCall(call), count });
+    }
+    return {
+        info: {
+            ok: true,
+            label: describeCall(locator.chain[0]),
+            text: found.text,
+            ...(value !== undefined && { value }),
+            attributes: found.attributes,
+            first: {
+                matcher: first.matcher,
+                ...("expected" in first && { expected: String(first.expected) }),
+            },
+            counts,
+        },
+        counts: calls,
+    };
+}