@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/recorder/capture.js

@@ -0,0 +1,198 @@
+/** Name of the window flag that tells the capture script to stop reporting (see `CAPTURE_OFF`) */
+const OFF_KEY = "samurai.recorder.off";
+/**
+ * Function declaration installed as a preload script, called as `(send)` where `send` is the recorder's
+ * channel. Reports what the tester does in the top-level document:
+ *
+ * - `{ type: "click", target, candidates, textEntry }`: a click, retargeted to the nearest interactive
+ *   element (a label click reports its control; the click the browser forwards to the control is dropped).
+ * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
+ *   values never leave the page: `secret` is set and `value` is left out.
+ * - `{ type: "assert", target, candidates, text, value }`: an Alt+click, which does not reach the page.
+ *   While Alt is held, the element under the pointer is outlined.
+ *
+ * `candidates` are locator calls for the element, most stable first (test id, role and name, label,
+ * text, css, and an absolute xpath that always exists). The recorder checks each one against the page.
+ * Runs in the page's own realm; a string, so no transpiler helper can end up in it.
+ */
+export const CAPTURE_SOURCE = String.raw `(send) => {
+  const OFF = Symbol.for("${OFF_KEY}");
+  const ON = Symbol.for("samurai.recorder.on");
+  const SEND = Symbol.for("samurai.recorder.send");
+  if (window !== window.top) return;
+  // A document that was recorded before gets the new channel; its listeners are already in place
+  window[OFF] = false;
+  window[SEND] = send;
+  if (window[ON]) return;
+  window[ON] = true;
+  const report = (message) => window[SEND](message);
+
+  const norm = (text) => String(text == null ? "" : text).replace(/\s+/g, " ").trim();
+  const textOf = (node) => norm(node.innerText != null ? node.innerText : node.textContent);
+  const NO_ROLE_TYPES = ["hidden", "password", "file", "color", "date", "datetime-local", "month", "time", "week"];
+  const TEXT_TYPES = ["", "text", "email", "search", "tel", "url", "password", "number"];
+
+  const roleOf = (el) => {
+    const explicit = norm(el.getAttribute("role")).split(" ")[0];
+    if (explicit) return explicit;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "a") return el.hasAttribute("href") ? "link" : undefined;
+    if (tag === "button" || tag === "summary") return "button";
+    if (tag === "select") return el.multiple || el.size > 1 ? "listbox" : "combobox";
+    if (tag === "textarea") return "textbox";
+    if (/^h[1-6]$/.test(tag)) return "heading";
+    if (tag === "img") return "img";
+    if (tag === "input") {
+      const type = (el.getAttribute("type") || "text").toLowerCase();
+      if (NO_ROLE_TYPES.indexOf(type) >= 0) return undefined;
+      if (type === "checkbox" || type === "radio") return type;
+      if (type === "button" || type === "submit" || type === "reset" || type === "image") return "button";
+      if (type === "range") return "slider";
+      if (type === "number") return "spinbutton";
+      if (type === "search") return "searchbox";
+      return "textbox";
+    }
+    return undefined;
+  };
+
+  const labelTexts = (el) => {
+    const texts = [];
+    if (el.labels) for (const label of el.labels) texts.push(textOf(label));
+    const by = el.getAttribute("aria-labelledby");
+    if (by) {
+      for (const id of by.split(/\s+/)) {
+        const named = id && document.getElementById(id);
+        if (named) texts.push(textOf(named));
+      }
+    }
+    const own = el.getAttribute("aria-label");
+    if (own) texts.push(norm(own));
+    return texts.filter(Boolean);
+  };
+
+  const nameOf = (el, role) => {
+    const labelled = labelTexts(el)[0];
+    if (labelled) return labelled;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "input") {
+      const type = (el.getAttribute("type") || "").toLowerCase();
+      return type === "submit" || type === "button" || type === "reset" ? norm(el.value) : "";
+    }
+    if (tag === "img") return norm(el.getAttribute("alt"));
+    if (role === "textbox" || role === "combobox" || role === "listbox") return "";
+    return textOf(el) || norm(el.getAttribute("title"));
+  };
+
+  const plain = (value) => value.indexOf('"') < 0 && value.indexOf("\\") < 0;
+
+  const xpathOf = (el) => {
+    const parts = [];
+    for (let node = el; node && node.nodeType === 1; node = node.parentElement) {
+      let index = 1;
+      for (let sibling = node.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+        if (sibling.tagName === node.tagName) index++;
+      }
+      parts.unshift(node.tagName.toLowerCase() + "[" + index + "]");
+    }
+    return "/" + parts.join("/");
+  };
+
+  const candidatesOf = (el) => {
+    const found = [];
+    const tag = el.tagName.toLowerCase();
+    const testId = el.getAttribute("data-testid");
+    if (testId) found.push({ method: "getByTestId", testId });
+    const role = roleOf(el);
+    if (role) {
+      const name = nameOf(el, role);
+      if (name && name.length <= 80) found.push({ method: "getByRole", role, name });
+    }
+    const label = labelTexts(el)[0];
+    if (label && label.length <= 80 && el.labels !== undefined) found.push({ method: "getByLabel", text: label });
+    const text = textOf(el);
+    if (text && text.length <= 60 && tag !== "input" && tag !== "textarea" && tag !== "select") {
+      found.push({ method: "getByText", text });
+    }
+    if (el.id && /^[A-Za-z][\w-]*$/.test(el.id) && !/\d{3,}/.test(el.id)) found.push({ method: "getByCss", css: "#" + el.id });
+    const name = el.getAttribute("name");
+    if (name && plain(name)) found.push({ method: "getByCss", css: tag + '[name="' + name + '"]' });
+    const placeholder = el.getAttribute("placeholder");
+    if (placeholder && plain(placeholder)) found.push({ method: "getByCss", css: tag + '[placeholder="' + placeholder + '"]' });
+    found.push({ method: "locator", xpath: xpathOf(el) });
+    return found;
+  };
+
+  const isTextEntry = (el) => {
+    const tag = el.tagName.toLowerCase();
+    if (tag === "textarea") return true;
+    if (tag === "input") return TEXT_TYPES.indexOf((el.getAttribute("type") || "").toLowerCase()) >= 0;
+    return Boolean(el.isContentEditable);
+  };
+
+  const INTERACTIVE = "a[href],button,input,select,textarea,label,summary,[role=button],[role=link],[role=checkbox],[role=radio],[role=tab],[role=menuitem],[role=option],[role=switch]";
+  const interactiveAt = (target) => {
+    const found = target.closest(INTERACTIVE) || target;
+    return found.tagName === "LABEL" && found.control ? found.control : found;
+  };
+
+  const off = () => window[OFF] === true;
+  let lastClick = { el: null, at: 0 };
+  let outlined = null;
+  let outlinedStyle = "";
+  const unhighlight = () => {
+    if (outlined) outlined.style.outline = outlinedStyle;
+    outlined = null;
+  };
+
+  document.addEventListener("click", (event) => {
+    if (off() || !event.isTrusted || !(event.target instanceof Element)) return;
+    if (event.altKey) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      unhighlight();
+      const el = event.target;
+      const hasValue = typeof el.value === "string" && el.tagName !== "BUTTON" && el.tagName !== "LI";
+      const secret = el.tagName === "INPUT" && (el.getAttribute("type") || "").toLowerCase() === "password";
+      report({
+        type: "assert",
+        target: el,
+        candidates: candidatesOf(el),
+        text: norm(el.textContent),
+        ...(hasValue && !secret && { value: el.value }),
+      });
+      return;
+    }
+    const el = interactiveAt(event.target);
+    const now = Date.now();
+    // The browser forwards a label click to its control as a second click
+    if (lastClick.el === el && now - lastClick.at < 150) return;
+    lastClick = { el, at: now };
+    report({ type: "click", target: el, candidates: candidatesOf(el), textEntry: isTextEntry(el) });
+  }, true);
+
+  document.addEventListener("input", (event) => {
+    const el = event.target;
+    if (off() || !event.isTrusted || !(el instanceof Element) || !isTextEntry(el) || el.isContentEditable) return;
+    const secret = el.tagName === "INPUT" && (el.getAttribute("type") || "").toLowerCase() === "password";
+    report({
+      type: "input",
+      target: el,
+      candidates: candidatesOf(el),
+      ...(secret
+        ? { secret: true, secretName: el.getAttribute("name") || el.id || "" }
+        : { value: el.value }),
+    });
+  }, true);
+
+  document.addEventListener("mousemove", (event) => {
+    if (off() || !event.altKey || !(event.target instanceof Element) || event.target === outlined) return;
+    unhighlight();
+    outlined = event.target;
+    outlinedStyle = outlined.style.outline;
+    outlined.style.outline = "2px solid #e5484d";
+  }, true);
+  document.addEventListener("keyup", (event) => { if (event.key === "Alt") unhighlight(); }, true);
+  window.addEventListener("blur", unhighlight);
+}`;
+/** Run in every loaded document to stop its capture script reporting and swallowing Alt+clicks */
+export const CAPTURE_OFF = `() => { window[Symbol.for("${OFF_KEY}")] = true; }`;

package/dist/recorder/index.d.ts

@@ -0,0 +1,3 @@
+export { Recorder, type RecorderOptions, type RecorderEvent, } from "./recorder.js";
+export { applyRecorderEvent } from "./apply.js";
+export { recordSpec, pickTest, type RecordSpecOptions, type RecordResult, } from "./session.js";

package/dist/recorder/index.js

@@ -0,0 +1,3 @@
+export { Recorder, } from "./recorder.js";
+export { applyRecorderEvent } from "./apply.js";
+export { recordSpec, pickTest, } from "./session.js";

package/dist/recorder/normalise.d.ts

@@ -0,0 +1,68 @@
+import type { LocatorSpec, Step } from "../steps/model.js";
+/** What the recorder does to the step list: a new step at `index`, or a step rewritten in place */
+export type RecorderEvent = {
+    op: "insert";
+    index: number;
+    step: Step;
+} | {
+    op: "replace";
+    index: number;
+    step: Step;
+};
+/** A page event whose element already has its locators */
+export type Observation = {
+    type: "click";
+    key: string;
+    locator: LocatorSpec;
+    textEntry: boolean;
+} | {
+    type: "input";
+    key: string;
+    locator: LocatorSpec;
+    value?: string;
+    secret?: boolean;
+    secretName?: string;
+} | {
+    type: "assert";
+    key: string;
+    locator: LocatorSpec;
+    text: string;
+    value?: string;
+};
+export interface NormaliserOptions {
+    /** Index the first recorded step gets */
+    at: number;
+    /** Relative URLs are written against this */
+    baseURL?: string;
+    /** A navigation within this many ms of the last action is a consequence of it. @default 2000 */
+    navigationWindow?: number;
+}
+/** The name a secret gets in `secrets.<NAME>`: the field's name or id, upper snake case */
+export declare function secretNameFor(hint: string | undefined): string;
+/**
+ * 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);
+ * - clicks that only focus a text field are dropped;
+ * - a navigation right after an action becomes `waitForNetworkIdle`, any other navigation a `goto`;
+ * - an Alt+click becomes an `expect`.
+ * Pure: the caller feeds it events and the times they happened.
+ */
+export declare class Normaliser {
+    private readonly options;
+    private next;
+    private lastFill;
+    private lastAction;
+    private lastStep;
+    private readonly window;
+    constructor(options: NormaliserOptions);
+    /** Index the next inserted step gets */
+    get nextIndex(): number;
+    private insert;
+    /** The path (and query) of `url` when it is inside the base URL, else `url` */
+    relative(url: string): string;
+    observe(observation: Observation, at: number): RecorderEvent[];
+    /** A top-level navigation started */
+    navigated(url: string, at: number): RecorderEvent[];
+    /** The page the recording starts on, written as a `goto` */
+    initialGoto(url: string): RecorderEvent[];
+}

package/dist/recorder/normalise.js

@@ -0,0 +1,104 @@
+const TEXT_LIMIT = 100;
+/** 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;
+}
+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() };
+}
+/**
+ * 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);
+ * - clicks that only focus a text field are dropped;
+ * - a navigation right after an action becomes `waitForNetworkIdle`, any other navigation a `goto`;
+ * - an Alt+click becomes an `expect`.
+ * Pure: the caller feeds it events and the times they happened.
+ */
+export class Normaliser {
+    constructor(options) {
+        this.options = options;
+        this.lastAction = -Infinity;
+        this.next = options.at;
+        this.window = options.navigationWindow ?? 2000;
+    }
+    /** Index the next inserted step gets */
+    get nextIndex() {
+        return this.next;
+    }
+    insert(step) {
+        this.lastStep = step;
+        return { op: "insert", index: this.next++, step };
+    }
+    /** The path (and query) of `url` when it is inside the base URL, else `url` */
+    relative(url) {
+        const base = this.options.baseURL?.replace(/\/+$/, "");
+        if (base &&
+            (url === base ||
+                url.startsWith(`${base}/`) ||
+                url.startsWith(`${base}?`) ||
+                url.startsWith(`${base}#`))) {
+            return url.slice(base.length) || "/";
+        }
+        return url;
+    }
+    observe(observation, at) {
+        if (observation.type === "click") {
+            if (observation.textEntry)
+                return []; // focusing a field: the fill that follows needs no click
+            this.lastFill = undefined;
+            this.lastAction = at;
+            return [this.insert({ kind: "click", locator: observation.locator })];
+        }
+        if (observation.type === "assert") {
+            this.lastFill = undefined;
+            return [
+                this.insert({
+                    kind: "expect",
+                    locator: observation.locator,
+                    not: false,
+                    expectation: expectationFor(observation.text, observation.value),
+                }),
+            ];
+        }
+        this.lastAction = at;
+        const step = {
+            kind: "fill",
+            locator: observation.locator,
+            value: observation.secret
+                ? { kind: "secret", name: secretNameFor(observation.secretName) }
+                : { kind: "literal", value: observation.value ?? "" },
+        };
+        if (this.lastFill?.key === observation.key) {
+            this.lastStep = step;
+            return [{ op: "replace", index: this.lastFill.index, step }];
+        }
+        this.lastFill = { key: observation.key, index: this.next };
+        return [this.insert(step)];
+    }
+    /** A top-level navigation started */
+    navigated(url, at) {
+        this.lastFill = undefined;
+        if (at - this.lastAction <= this.window) {
+            this.lastAction = -Infinity;
+            return this.lastStep?.kind === "waitForNetworkIdle"
+                ? []
+                : [this.insert({ kind: "waitForNetworkIdle" })];
+        }
+        return [this.insert({ kind: "goto", url: this.relative(url) })];
+    }
+    /** The page the recording starts on, written as a `goto` */
+    initialGoto(url) {
+        return [this.insert({ kind: "goto", url: this.relative(url) })];
+    }
+}

package/dist/recorder/ranking.d.ts

@@ -0,0 +1,9 @@
+import type Page from "../browser/page.js";
+import type { ElementHandle } from "../script/element-handle.js";
+import type { LocatorCall, LocatorSpec } from "../steps/model.js";
+/**
+ * Picks the locators for `target` from `candidates` (most stable first). Only a candidate that matches
+ * exactly one element, the target, is used: the first becomes the primary, up to `maxFallbacks` more
+ * become its fallbacks. Returns undefined when no candidate qualifies.
+ */
+export declare function rankLocator(page: Page, target: ElementHandle, candidates: readonly LocatorCall[], maxFallbacks?: number): Promise<LocatorSpec | undefined>;

package/dist/recorder/ranking.js

@@ -0,0 +1,21 @@
+import { locatorFromSpec } from "../steps/build.js";
+/**
+ * Picks the locators for `target` from `candidates` (most stable first). Only a candidate that matches
+ * exactly one element, the target, is used: the first becomes the primary, up to `maxFallbacks` more
+ * become its fallbacks. Returns undefined when no candidate qualifies.
+ */
+export async function rankLocator(page, target, candidates, maxFallbacks = 2) {
+    const verified = [];
+    for (const candidate of candidates) {
+        if (verified.length > maxFallbacks)
+            break;
+        const found = await locatorFromSpec(page, {
+            chain: [candidate],
+            fallbacks: [],
+        }).elements();
+        if (found.length === 1 && found[0].sharedId === target.sharedId)
+            verified.push(candidate);
+    }
+    const [primary, ...fallbacks] = verified;
+    return (primary && { chain: [primary], fallbacks: fallbacks.map((call) => [call]) });
+}

package/dist/recorder/recorder.d.ts

@@ -0,0 +1,52 @@
+import type Page from "../browser/page.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type RecorderEvent } from "./normalise.js";
+export type { RecorderEvent } from "./normalise.js";
+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;
+}
+/**
+ * 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 declare class Recorder {
+    private readonly page;
+    private readonly connector;
+    private readonly context;
+    private readonly normaliser;
+    private readonly options;
+    private readonly channel;
+    private readonly queue;
+    private readonly known;
+    private stopped;
+    private constructor();
+    static start(target: {
+        page: Page;
+        connector: BiDiConnector;
+        context: string;
+    }, options: RecorderOptions): Promise<Recorder>;
+    private readonly onMessage;
+    private readonly onNavigation;
+    private subscription;
+    private preload;
+    private begin;
+    private enqueue;
+    private emit;
+    private locatorFor;
+    private handle;
+    private release;
+    /** Stops recording. Events already received are still processed and reported first */
+    stop(): Promise<void>;
+}

package/dist/recorder/recorder.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import logger from "../logger/index.js";
+import { addPreload, runInLoadedContexts } from "../script/preload.js";
+import { ChannelArg, fromRemoteValue } from "../script/serialize.js";
+import { ElementHandle } from "../script/element-handle.js";
+import { CAPTURE_OFF, CAPTURE_SOURCE } from "./capture.js";
+import { Normaliser, } from "./normalise.js";
+import { rankLocator } from "./ranking.js";
+/**
+ * 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) {
+        this.page = page;
+        this.connector = connector;
+        this.context = context;
+        this.normaliser = normaliser;
+        this.options = options;
+        this.channel = channel;
+        this.queue = { tail: Promise.resolve() };
+        this.known = new Map();
+        this.stopped = false;
+        this.onMessage = (params) => {
+            if (params.channel !== this.channel ||
+                params.source.context !== this.context)
+                return;
+            const message = fromRemoteValue(params.data);
+            this.enqueue(async () => this.handle(message));
+        };
+        this.onNavigation = (params) => {
+            if (params.context !== this.context || params.url === "about:blank")
+                return;
+            this.known.clear();
+            this.enqueue(async () => this.emit(this.normaliser.navigated(params.url, Date.now())));
+        };
+    }
+    static async start(target, options) {
+        const at = options.at ?? 0;
+        const normaliser = new Normaliser({
+            at,
+            ...(options.baseURL !== undefined && { baseURL: options.baseURL }),
+        });
+        const recorder = new Recorder(target.page, target.connector, target.context, normaliser, options, `samurai-recorder-${randomUUID()}`);
+        await recorder.begin(options.initialGoto ?? true);
+        return recorder;
+    }
+    async begin(initialGoto) {
+        this.connector.onEvent("script.message", this.onMessage);
+        this.connector.onEvent("browsingContext.navigationStarted", this.onNavigation);
+        try {
+            this.subscription = await this.connector.subscribe([
+                "script.message",
+                "browsingContext.navigationStarted",
+            ]);
+            if (initialGoto) {
+                const url = await this.page.url();
+                if (url !== "about:blank")
+                    this.emit(this.normaliser.initialGoto(url));
+            }
+            this.preload = await addPreload(this.connector, {
+                source: CAPTURE_SOURCE,
+                contexts: [this.context],
+                arguments: [new ChannelArg(this.channel)],
+                onRunError: "log",
+            });
+        }
+        catch (err) {
+            await this.release();
+            throw err;
+        }
+    }
+    enqueue(work) {
+        this.queue.tail = this.queue.tail.then(work).catch((err) => {
+            logger.warn("Recorder could not process an event", { err });
+        });
+    }
+    emit(events) {
+        if (this.stopped)
+            return;
+        for (const event of events)
+            this.options.onEvent(event);
+    }
+    async locatorFor(message) {
+        const { sharedId } = message.target;
+        if (this.known.has(sharedId))
+            return this.known.get(sharedId);
+        const spec = await rankLocator(this.page, message.target, message.candidates);
+        this.known.set(sharedId, spec);
+        return spec;
+    }
+    async handle(message) {
+        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);
+            return;
+        }
+        const key = message.target.sharedId;
+        const observation = message.type === "click"
+            ? { type: "click", key, locator, textEntry: message.textEntry === true }
+            : 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,
+                    }),
+                };
+        this.emit(this.normaliser.observe(observation, Date.now()));
+    }
+    async release() {
+        this.connector.offEvent("script.message", this.onMessage);
+        this.connector.offEvent("browsingContext.navigationStarted", this.onNavigation);
+        await Promise.allSettled([
+            this.subscription?.unsubscribe(),
+            this.preload?.dispose(),
+        ]);
+    }
+    /** Stops recording. Events already received are still processed and reported first */
+    async stop() {
+        if (this.stopped)
+            return;
+        await runInLoadedContexts(this.connector, {
+            source: CAPTURE_OFF,
+            contexts: [this.context],
+            onRunError: "log",
+        }).catch(() => undefined);
+        await this.queue.tail;
+        this.stopped = true;
+        await this.release();
+    }
+}

package/dist/recorder/session.d.ts

@@ -0,0 +1,49 @@
+import { Browser } from "../browser/browser.js";
+import type Page from "../browser/page.js";
+import { type ProjectOptions } from "../runner/project.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 */
+    file: string;
+    /** The test to record into: its full name (or a part that is unique), or its index in the file. Optional when the file has one test */
+    test?: string | number;
+    /** Add a test with this title to the file (and create the file) instead of recording into an existing one */
+    create?: string;
+    /**
+     * Index the first recorded step gets. @default after the last step of the test.
+     * The browser starts on `url` (or the base URL), not where steps `0…at-1` would leave it
+     */
+    at?: number;
+    /** The page to start on. @default the environment's base URL; without one the browser starts blank */
+    url?: string;
+    /** The browser's debugging port. @default 9223 */
+    port?: number;
+    /** Aborting ends the recording, like closing the browser window */
+    signal?: AbortSignal;
+    /** Called after each step is written to the file, with the file's new content */
+    onEvent?: (event: RecorderEvent, source: string) => void;
+    /** Called once the browser is open and recording */
+    onStarted?: (context: {
+        page: Page;
+        browser: Browser;
+    }) => void | Promise<void>;
+}
+export interface RecordResult {
+    file: string;
+    /** Full name of the test the steps went into */
+    test: string;
+    events: RecorderEvent[];
+    /** Names the recorded steps read with `secrets.<NAME>`: they must be set before the test can run */
+    secrets: 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.
+ * @example
+ *  await recordSpec({ file: "tests/login.spec.ts", create: "signs in", environment: "staging" });
+ */
+export declare function recordSpec(options: RecordSpecOptions): Promise<RecordResult>;