@itmetsam/samurai-framework 0.22.1 → 0.22.2

package/dist/capabilities.d.ts

@@ -38,8 +38,12 @@ export declare const CAPABILITIES: {
     readonly flowNodeFolders: 2;
     /** `nodeFolder(nodeId, browser)` from `./flows/run`: a flow node's folder under `outputDir` (version 2 takes the browser). */
     readonly nodeFolder: 2;
-    /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
-    readonly assertionMatchers: 2;
+    /**
+     * Assertion matchers in the framework and the step codec. Version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`,
+     * `toHaveClass` and `toHaveCSS`. Version 3 adds `toBeFocused`, `toBeDisabled`, `toBeEditable`, `toBeAttached`,
+     * `toBeInViewport`, `toBeEmpty`, `toHaveId`, `toHaveAccessibleName` and `toHaveAccessibleDescription` to the codec.
+     */
+    readonly assertionMatchers: 3;
     /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
     readonly pageAssertions: true;
     /**
@@ -50,6 +54,16 @@ export declare const CAPABILITIES: {
     readonly testInputsOutputs: true;
     /** A flow runs once per browser: `browser` on every flow event, `flow-done`, `runFlowInProject` resolving to `FlowRunResult`. */
     readonly flowPerBrowser: true;
+    /** The codec's `check`, `uncheck`, `selectOption`, `hover`, `dblclick` and `clear` steps. */
+    readonly actionSteps: true;
+    /**
+     * The codec's locator forms: `exact` and RegExp text and name, `getByPlaceholder` / `getByAltText` / `getByTitle`, the
+     * `getByRole` options `level`, `checked`, `pressed`, `expanded`, `selected`, `disabled` and `includeHidden`, and the
+     * `nth`, `first`, `last` and `filter({ hasText })` calls. `LocatorCall.text` and `.name` can be a RegExp.
+     */
+    readonly locatorForms: true;
+    /** The recorder writes a `check` / `uncheck` for a checkbox or radio click and a `selectOption` for a `<select>` choice. */
+    readonly recorderActionSteps: true;
 };
 /** The shape of {@link CAPABILITIES}. */
 export type Capabilities = typeof CAPABILITIES;

package/dist/capabilities.js

@@ -38,8 +38,12 @@ export const CAPABILITIES = {
     flowNodeFolders: 2,
     /** `nodeFolder(nodeId, browser)` from `./flows/run`: a flow node's folder under `outputDir` (version 2 takes the browser). */
     nodeFolder: 2,
-    /** Assertion matchers version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`, `toHaveClass` and `toHaveCSS`, in the framework and the step codec. */
-    assertionMatchers: 2,
+    /**
+     * Assertion matchers in the framework and the step codec. Version 2: `toBeHidden`, `toBeEnabled`, `toBeChecked`,
+     * `toHaveClass` and `toHaveCSS`. Version 3 adds `toBeFocused`, `toBeDisabled`, `toBeEditable`, `toBeAttached`,
+     * `toBeInViewport`, `toBeEmpty`, `toHaveId`, `toHaveAccessibleName` and `toHaveAccessibleDescription` to the codec.
+     */
+    assertionMatchers: 3,
     /** `expect(page).toHaveURL` and `toHaveTitle`, and the `expectPage` step in the step codec. */
     pageAssertions: true,
     /**
@@ -50,4 +54,14 @@ export const CAPABILITIES = {
     testInputsOutputs: true,
     /** A flow runs once per browser: `browser` on every flow event, `flow-done`, `runFlowInProject` resolving to `FlowRunResult`. */
     flowPerBrowser: true,
+    /** The codec's `check`, `uncheck`, `selectOption`, `hover`, `dblclick` and `clear` steps. */
+    actionSteps: true,
+    /**
+     * The codec's locator forms: `exact` and RegExp text and name, `getByPlaceholder` / `getByAltText` / `getByTitle`, the
+     * `getByRole` options `level`, `checked`, `pressed`, `expanded`, `selected`, `disabled` and `includeHidden`, and the
+     * `nth`, `first`, `last` and `filter({ hasText })` calls. `LocatorCall.text` and `.name` can be a RegExp.
+     */
+    locatorForms: true,
+    /** The recorder writes a `check` / `uncheck` for a checkbox or radio click and a `selectOption` for a `<select>` choice. */
+    recorderActionSteps: true,
 };

package/dist/recorder/capture.d.ts

@@ -7,6 +7,9 @@
  *
  * - `{ type: "click", target, candidates, unique, 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).
+ *   On a checkbox or radio it also carries `checked`, the state the click leaves.
+ * - `{ type: "select", target, candidates, option }`: a trusted `change` of a single-choice `<select>`; `option` is
+ *   `{ value }`, else `{ label }`, else `{ index }` of the chosen option.
  * - `{ 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: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a

package/dist/recorder/capture.js

@@ -14,6 +14,9 @@ const RUN_KEY = "samurai.recorder.run";
  *
  * - `{ type: "click", target, candidates, unique, 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).
+ *   On a checkbox or radio it also carries `checked`, the state the click leaves.
+ * - `{ type: "select", target, candidates, option }`: a trusted `change` of a single-choice `<select>`; `option` is
+ *   `{ value }`, else `{ label }`, else `{ index }` of the chosen option.
  * - `{ 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: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
@@ -76,7 +79,21 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     if (event.detail === 0 && el.form && el.form === lastEnter.form && now - lastEnter.at < 150) return;
     lastClick = { el, at: now };
     const candidates = candidatesOf(el);
-    report({ type: "click", target: el, candidates, unique: uniqueOf(el, candidates), textEntry: isTextEntry(el) });
+    // A checkbox or radio click is a check or an uncheck, by the state it leaves: the browser has already flipped a
+    // control that is the click's own target, while a label's click flips its control only after this listener
+    const checkable = el.tagName === "INPUT" && (el.type === "checkbox" || el.type === "radio");
+    const checked = checkable ? (el.type === "radio" ? true : event.target === el ? el.checked : !el.checked) : undefined;
+    report({ type: "click", target: el, candidates, unique: uniqueOf(el, candidates), textEntry: isTextEntry(el), ...(checked !== undefined && { checked }) });
+  }, true);
+
+  // A choice in a <select> (one that takes a single option; several are a list, which stays custom code)
+  document.addEventListener("change", (event) => {
+    if (inToolbar(event)) return;
+    const el = event.target;
+    if (off() || !event.isTrusted || !(el instanceof HTMLSelectElement) || el.multiple || !el.selectedOptions.length) return;
+    const chosen = el.selectedOptions[0];
+    const option = chosen.value !== "" ? { value: chosen.value } : chosen.label !== "" ? { label: chosen.label } : { index: chosen.index };
+    report({ type: "select", target: el, candidates: candidatesOf(el), option });
   }, true);
 
   document.addEventListener("input", (event) => {

package/dist/recorder/normalise.d.ts

@@ -1,4 +1,4 @@
-import type { Expectation, FileEntry, LocatorSpec, PageExpectation, Step, TestInput } from "../steps/model.js";
+import type { Expectation, FileEntry, LocatorSpec, PageExpectation, SelectChoice, Step, TestInput } from "../steps/model.js";
 /** What the recorder does to the step list: a new step at `index`, a step rewritten in place, or one taken out */
 export type RecorderEvent = 
 /** `declare`: an input the step reads, declared with its default before the step goes in */
@@ -21,6 +21,15 @@ export type Observation = {
     key: string;
     locator: LocatorSpec;
     textEntry: boolean;
+    /** Of a checkbox or radio: whether the click leaves it checked. Recorded as `check` or `uncheck` */
+    checked?: boolean;
+}
+/** A `<select>` changed to this option */
+ | {
+    type: "select";
+    key: string;
+    locator: LocatorSpec;
+    option: SelectChoice;
 } | {
     type: "input";
     key: string;
@@ -143,6 +152,8 @@ export declare class Normaliser {
     private pickerCancelled;
     private filesSet;
     private clicked;
+    /** A choice in a `<select>`; the click that opened it, just before, is the same step */
+    private selected;
     private pressed;
     /** An Alt+click */
     private asserted;

package/dist/recorder/normalise.js

@@ -105,6 +105,8 @@ export class Normaliser {
                 return this.filesSet(observation, at);
             case "click":
                 return this.clicked(observation, at);
+            case "select":
+                return this.selected(observation, at);
             case "press":
                 return this.pressed(observation, at);
             case "assert":
@@ -163,12 +165,38 @@ export class Normaliser {
             return []; // focusing a field: the fill that follows needs no click
         this.lastFill = undefined;
         this.lastAction = at;
+        if (observation.checked !== undefined)
+            return [
+                this.insert({
+                    kind: observation.checked ? "check" : "uncheck",
+                    locator: observation.locator,
+                }),
+            ];
         const events = [
             this.insert({ kind: "click", locator: observation.locator }),
         ];
-        this.lastClick = { index: this.next - 1, at };
+        this.lastClick = { index: this.next - 1, at, key: observation.key };
         return events;
     }
+    /** A choice in a `<select>`; the click that opened it, just before, is the same step */
+    selected(observation, at) {
+        this.lastFill = undefined;
+        this.lastAction = at;
+        const step = {
+            kind: "selectOption",
+            locator: observation.locator,
+            option: observation.option,
+        };
+        const click = this.lastClick;
+        if (click &&
+            click.key === observation.key &&
+            click.index === this.next - 1) {
+            this.lastClick = undefined;
+            this.lastStep = step;
+            return [{ op: "replace", index: click.index, step }];
+        }
+        return [this.insert(step)];
+    }
     pressed(observation, at) {
         // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
         this.lastFill = undefined;

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

@@ -1,5 +1,5 @@
 import type { ElementHandle } from "../script/element-handle.js";
-import type { LocatorCall, LocatorSpec } from "../steps/model.js";
+import type { LocatorCall, LocatorSpec, SelectChoice } from "../steps/model.js";
 import type { Observation } from "./normalise.js";
 /** What the files capture script sends */
 export type FilesMessage = {
@@ -20,12 +20,16 @@ export type FilesMessage = {
 };
 /** What the capture script sends */
 export interface PageMessage {
-    type: "click" | "input" | "press" | "assert";
+    type: "click" | "input" | "press" | "assert" | "select";
     target: ElementHandle;
     candidates: LocatorCall[];
     /** Of a click or press: the candidates that matched only the target when it happened, checked in the page */
     unique?: LocatorCall[];
     textEntry?: boolean;
+    /** Of a click on a checkbox or radio: whether it leaves the control checked */
+    checked?: boolean;
+    /** Of a `select` message: the option the tester chose */
+    option?: SelectChoice;
     /** The key of a `press` message */
     pressed?: string;
     value?: string;

package/dist/recorder/page-messages.js

@@ -2,25 +2,33 @@
 export function observationFor(message, locator) {
     const key = message.target.sharedId;
     return message.type === "click"
-        ? { type: "click", key, locator, textEntry: message.textEntry === true }
-        : message.type === "press"
-            ? { type: "press", key, locator, pressed: message.pressed ?? "" }
-            : message.type === "assert"
-                ? {
-                    type: "assert",
-                    key,
-                    locator,
-                    text: message.text ?? "",
-                    ...(message.value !== undefined && { value: message.value }),
-                }
-                : {
-                    type: "input",
-                    key,
-                    locator,
-                    ...(message.value !== undefined && { value: message.value }),
-                    ...(message.secret && { secret: true }),
-                    ...(message.secretName !== undefined && {
-                        secretName: message.secretName,
-                    }),
-                };
+        ? {
+            type: "click",
+            key,
+            locator,
+            textEntry: message.textEntry === true,
+            ...(message.checked !== undefined && { checked: message.checked }),
+        }
+        : message.type === "select"
+            ? { type: "select", key, locator, option: message.option ?? "" }
+            : message.type === "press"
+                ? { type: "press", key, locator, pressed: message.pressed ?? "" }
+                : message.type === "assert"
+                    ? {
+                        type: "assert",
+                        key,
+                        locator,
+                        text: message.text ?? "",
+                        ...(message.value !== undefined && { value: message.value }),
+                    }
+                    : {
+                        type: "input",
+                        key,
+                        locator,
+                        ...(message.value !== undefined && { value: message.value }),
+                        ...(message.secret && { secret: true }),
+                        ...(message.secretName !== undefined && {
+                            secretName: message.secretName,
+                        }),
+                    };
 }

package/dist/recorder/toolbar/inspect.js

@@ -1,5 +1,6 @@
 import { callFunction } from "../../script/call-function.js";
 import { locatorFromSpec } from "../../steps/build.js";
+import { callToSource } from "../../steps/emit.js";
 import { CANDIDATES_JS } from "../candidates.js";
 import { expectationFor } from "../expectation.js";
 import { TOOLBAR_SANDBOX } from "./protocol.js";
@@ -45,19 +46,25 @@ function describeCall(call) {
         case "getByRole":
             return call.name === undefined
                 ? call.role
-                : `${call.role} "${call.name}"`;
+                : `${call.role} ${quoted(call.name)}`;
         case "getByLabel":
-            return `label "${call.text}"`;
+            return `label ${quoted(call.text)}`;
         case "getByText":
-            return `text "${call.text}"`;
+            return `text ${quoted(call.text)}`;
         case "getByTestId":
             return `test id "${call.testId}"`;
         case "getByCss":
             return call.css;
         case "locator":
             return call.xpath;
+        default:
+            return callToSource(call);
     }
 }
+/** A text as the panel shows it: in quotes, a RegExp as written */
+const quoted = (text) => typeof text === "string"
+    ? `"${text}"`
+    : `/${text.regex.source}/${text.regex.flags}`;
 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

package/dist/steps/build.js

@@ -1,32 +1,56 @@
+/** The RegExp or string a matcher stands for */
+function textFromMatcher(matcher) {
+    return typeof matcher === "string"
+        ? matcher
+        : new RegExp(matcher.regex.source, matcher.regex.flags);
+}
+/** `options` without the keys that are undefined, or undefined when nothing is left */
+function defined(options) {
+    const entries = Object.entries(options).filter(([, v]) => v !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+function apply(target, call) {
+    switch (call.method) {
+        case "locator":
+            return target.locator(call.xpath);
+        case "getByCss":
+            return target.getByCss(call.css);
+        case "getByText":
+        case "getByLabel": {
+            const { exact, match, ignoreCase } = call;
+            return target[call.method](textFromMatcher(call.text), defined({ exact, match, ignoreCase }));
+        }
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+            return target[call.method](textFromMatcher(call.text), defined({ exact: call.exact }));
+        case "getByRole": {
+            const { method, role, name, ...options } = call;
+            return target.getByRole(role, defined({
+                ...options,
+                ...(name !== undefined && { name: textFromMatcher(name) }),
+            }));
+        }
+        case "getByTestId":
+            return target.getByTestId(call.testId);
+        case "nth":
+        case "first":
+        case "last":
+        case "filter": {
+            if (!("nth" in target))
+                throw new Error(`${call.method} needs a locator to narrow`);
+            return call.method === "nth"
+                ? target.nth(call.index)
+                : call.method === "filter"
+                    ? target.filter({ hasText: textFromMatcher(call.hasText) })
+                    : target[call.method]();
+        }
+    }
+}
 function fromCalls(page, calls) {
     const [first, ...rest] = calls;
     if (!first)
         throw new Error("A locator needs at least one call");
-    const apply = (target, call) => {
-        const text = {
-            ...(call.method !== "locator" &&
-                call.method !== "getByCss" &&
-                call.method !== "getByTestId" &&
-                call.method !== "getByRole" && {
-                ...(call.match !== undefined && { match: call.match }),
-                ...(call.ignoreCase !== undefined && { ignoreCase: call.ignoreCase }),
-            }),
-        };
-        switch (call.method) {
-            case "locator":
-                return target.locator(call.xpath);
-            case "getByCss":
-                return target.getByCss(call.css);
-            case "getByText":
-                return target.getByText(call.text, text);
-            case "getByLabel":
-                return target.getByLabel(call.text, text);
-            case "getByRole":
-                return target.getByRole(call.role, call.name === undefined ? undefined : { name: call.name });
-            case "getByTestId":
-                return target.getByTestId(call.testId);
-        }
-    };
     return rest.reduce((locator, call) => apply(locator, call), apply(page, first));
 }
 /** The locator a step's `LocatorSpec` stands for, with its fallbacks */

package/dist/steps/emit.js

@@ -17,13 +17,29 @@ export function filesToSource(files) {
 }
 /** A name that can follow a `.` or stand as an object key unquoted */
 export const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
-function textOptions(call) {
-    const parts = [
-        call.match !== undefined && `match: ${str(call.match)}`,
-        call.ignoreCase !== undefined && `ignoreCase: ${call.ignoreCase}`,
-    ].filter(Boolean);
+/** `, { a: 1, b: "x" }` from key and source pairs; a pair without source is left out, and so is an empty object */
+function optionsToSource(pairs) {
+    const parts = pairs
+        .filter(([, source]) => source !== undefined)
+        .map(([key, source]) => `${key}: ${source}`);
     return parts.length ? `, { ${parts.join(", ")} }` : "";
 }
+/** A string, number or boolean as source, or undefined when it isn't set */
+const literal = (value) => value === undefined
+    ? undefined
+    : typeof value === "string"
+        ? str(value)
+        : String(value);
+const ROLE_OPTIONS = [
+    "exact",
+    "level",
+    "checked",
+    "pressed",
+    "expanded",
+    "selected",
+    "disabled",
+    "includeHidden",
+];
 export function callToSource(call) {
     switch (call.method) {
         case "locator":
@@ -32,11 +48,32 @@ export function callToSource(call) {
             return `getByCss(${str(call.css)})`;
         case "getByText":
         case "getByLabel":
-            return `${call.method}(${str(call.text)}${textOptions(call)})`;
+            return `${call.method}(${matcherToSource(call.text)}${optionsToSource([
+                ["exact", literal(call.exact)],
+                ["match", literal(call.match)],
+                ["ignoreCase", literal(call.ignoreCase)],
+            ])})`;
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+            return `${call.method}(${matcherToSource(call.text)}${optionsToSource([["exact", literal(call.exact)]])})`;
         case "getByRole":
-            return `getByRole(${str(call.role)}${call.name === undefined ? "" : `, { name: ${str(call.name)} }`})`;
+            return `getByRole(${str(call.role)}${optionsToSource([
+                [
+                    "name",
+                    call.name === undefined ? undefined : matcherToSource(call.name),
+                ],
+                ...ROLE_OPTIONS.map((key) => [key, literal(call[key])]),
+            ])})`;
         case "getByTestId":
             return `getByTestId(${str(call.testId)})`;
+        case "nth":
+            return `nth(${call.index})`;
+        case "first":
+        case "last":
+            return `${call.method}()`;
+        case "filter":
+            return `filter({ hasText: ${matcherToSource(call.hasText)} })`;
     }
 }
 const chainToSource = (chain) => ["page", ...chain.map(callToSource)].join(".");
@@ -86,6 +123,12 @@ function expectationToSource(expectation, output) {
         case "toBeHidden":
         case "toBeEnabled":
         case "toBeChecked":
+        case "toBeFocused":
+        case "toBeDisabled":
+        case "toBeEditable":
+        case "toBeAttached":
+        case "toBeInViewport":
+        case "toBeEmpty":
             return `${expectation.matcher}()`;
         case "toHaveAttribute":
             return `toHaveAttribute(${str(expectation.name)}, ${matcherToSource(expectation.expected)}${tail})`;
@@ -97,6 +140,12 @@ function expectationToSource(expectation, output) {
             return `${expectation.matcher}(${matcherToSource(expectation.expected)}${tail})`;
     }
 }
+function choiceToSource(option) {
+    if (typeof option === "string")
+        return str(option);
+    const [key, value] = Object.entries(option)[0];
+    return `{ ${key}: ${typeof value === "string" ? str(value) : value} }`;
+}
 /** The statement for a step, on one line */
 export function stepToSource(step) {
     switch (step.kind) {
@@ -106,6 +155,14 @@ export function stepToSource(step) {
             return `await ${locatorToSource(step.locator)}.click();`;
         case "fill":
             return `await ${locatorToSource(step.locator)}.fill(${valueToSource(step.value)}${outputOption(step.output)});`;
+        case "check":
+        case "uncheck":
+        case "hover":
+        case "dblclick":
+        case "clear":
+            return `await ${locatorToSource(step.locator)}.${step.kind}();`;
+        case "selectOption":
+            return `await ${locatorToSource(step.locator)}.selectOption(${choiceToSource(step.option)});`;
         case "press":
             return `await ${locatorToSource(step.locator)}.press(${str(step.key)});`;
         case "expect":

package/dist/steps/index.d.ts

@@ -3,4 +3,4 @@ export { applyEdit, type StepEdit } from "./edit.js";
 export { stepToSource, locatorToSource, callToSource, filesToSource, valueToSource, } from "./emit.js";
 export { formatSize, humanSize, parseSize, sizeFromSource } from "./files.js";
 export { locatorFromSpec } from "./build.js";
-export type { Expectation, FileEntry, GeneratedFileSpec, LocatorCall, LocatorSpec, PageExpectation, ParsedStep, ParsedTest, Step, TextMatcher, TestInput, TextValue, UnparsedTest, } from "./model.js";
+export type { Expectation, FileEntry, GeneratedFileSpec, LocatorCall, LocatorSpec, PageExpectation, SelectChoice, ParsedStep, ParsedTest, Step, TextMatcher, TestInput, TextValue, UnparsedTest, } from "./model.js";

package/dist/steps/model.d.ts

@@ -1,5 +1,9 @@
 import type { Modifier } from "../types/test.js";
-/** One call of a locator expression, as written in a spec: `page.getByRole("button", { name: "Save" })` */
+/**
+ * One call of a locator expression, as written in a spec: `page.getByRole("button", { name: "Save" })`.
+ * A RegExp text or name is tested as written, so it never comes with `exact`, `match` or `ignoreCase`.
+ * `nth`, `first`, `last` and `filter` narrow the calls before them, so they never start a chain
+ */
 export type LocatorCall = {
     method: "locator";
     xpath: string;
@@ -7,22 +11,46 @@ export type LocatorCall = {
     method: "getByCss";
     css: string;
 } | {
-    method: "getByText";
-    text: string;
+    method: "getByText" | "getByLabel";
+    text: TextMatcher;
+    /** `false`: a case-insensitive substring. Absent: the framework's default, a full case-sensitive match */
+    exact?: boolean;
     match?: "full" | "partial";
     ignoreCase?: boolean;
 } | {
-    method: "getByLabel";
-    text: string;
-    match?: "full" | "partial";
-    ignoreCase?: boolean;
+    method: "getByPlaceholder" | "getByAltText" | "getByTitle";
+    text: TextMatcher;
+    exact?: boolean;
 } | {
     method: "getByRole";
     role: string;
-    name?: string;
+    name?: TextMatcher;
+    exact?: boolean;
+    /** The heading level */
+    level?: number;
+    checked?: boolean | "mixed";
+    pressed?: boolean | "mixed";
+    expanded?: boolean;
+    selected?: boolean;
+    disabled?: boolean;
+    includeHidden?: boolean;
 } | {
     method: "getByTestId";
     testId: string;
+}
+/** The n-th match, 0-based; a negative index counts from the end */
+ | {
+    method: "nth";
+    index: number;
+} | {
+    method: "first";
+} | {
+    method: "last";
+}
+/** Keeps the matches whose text contains the string (case-insensitive) or matches the RegExp */
+ | {
+    method: "filter";
+    hasText: TextMatcher;
 };
 /** A chain of locator calls on `page`, and the locators `withFallbacks` falls back to, most preferred first */
 export interface LocatorSpec {
@@ -53,7 +81,7 @@ export type TextMatcher = string | {
     };
 };
 export type Expectation = {
-    matcher: "toBeVisible" | "toBeHidden" | "toBeEnabled" | "toBeChecked";
+    matcher: "toBeVisible" | "toBeHidden" | "toBeEnabled" | "toBeChecked" | "toBeFocused" | "toBeDisabled" | "toBeEditable" | "toBeAttached" | "toBeInViewport" | "toBeEmpty";
 } | {
     matcher: "toHaveClass";
     expected: TextMatcher;
@@ -62,7 +90,7 @@ export type Expectation = {
     name: string;
     expected: TextMatcher;
 } | {
-    matcher: "toHaveText" | "toContainText" | "toHaveValue";
+    matcher: "toHaveText" | "toContainText" | "toHaveValue" | "toHaveId" | "toHaveAccessibleName" | "toHaveAccessibleDescription";
     expected: TextMatcher;
 } | {
     matcher: "toHaveAttribute";
@@ -93,6 +121,17 @@ export type FileEntry = {
 } | {
     generate: GeneratedFileSpec;
 };
+/**
+ * The option `selectOption` chooses: a string (the option's value or its label), or exactly one of its `value`,
+ * `label` or position
+ */
+export type SelectChoice = string | {
+    value: string;
+} | {
+    label: string;
+} | {
+    index: number;
+};
 /** The restricted set of statements the recorder writes. Anything else in a test is a `custom` step */
 export type Step = {
     kind: "goto";
@@ -101,6 +140,17 @@ export type Step = {
     kind: "click";
     locator: LocatorSpec;
 }
+/** An action on an element with no argument: ticks or unticks it, moves the pointer over it, double-clicks it, empties a field */
+ | {
+    kind: "check" | "uncheck" | "hover" | "dblclick" | "clear";
+    locator: LocatorSpec;
+}
+/** Chooses one option of a `<select>`; a list of options is `custom` */
+ | {
+    kind: "selectOption";
+    locator: LocatorSpec;
+    option: SelectChoice;
+}
 /** `output` saves the typed value as that output, `{ output: "name" }` */
  | {
     kind: "fill";

package/dist/steps/parse/call.js

@@ -1,48 +1,131 @@
 import ts from "typescript";
-import { readObject, stringOf } from "./literals.js";
-function readCall(method, args) {
-    const first = stringOf(args[0]);
-    if (first === undefined)
+import { readTextMatcher } from "./expectation.js";
+import { booleanOf, integerOf, readProps, stringOf } from "./literals.js";
+/** The calls that narrow the ones before them, so they can't start a chain on `page` */
+const NARROWING = ["nth", "first", "last", "filter"];
+const MATCHES = ["full", "partial"];
+const TRISTATE = ["checked", "pressed"];
+const FLAGS = ["expanded", "selected", "disabled", "includeHidden"];
+const ROLE_KEYS = ["name", "exact", "level", ...TRISTATE, ...FLAGS];
+/** `{ exact, match, ignoreCase }` of a text call, as far as the call allows */
+function readTextOptions(node, allowed) {
+    if (!node)
+        return {};
+    const props = readProps(node, allowed);
+    if (!props)
+        return undefined;
+    const { exact, match, ignoreCase } = props;
+    const matchValue = stringOf(match);
+    if ((exact && booleanOf(exact) === undefined) ||
+        (ignoreCase && booleanOf(ignoreCase) === undefined) ||
+        (match && (matchValue === undefined || !MATCHES.includes(matchValue))))
+        return undefined;
+    return {
+        ...(exact && { exact: booleanOf(exact) }),
+        ...(match && { match: matchValue }),
+        ...(ignoreCase && { ignoreCase: booleanOf(ignoreCase) }),
+    };
+}
+/** A call that takes a text (or RegExp) and the options `allowed`; a RegExp takes none */
+function readTextCall(method, args, allowed) {
+    const text = readTextMatcher(args[0]);
+    if (text === undefined || args.length > 2)
+        return undefined;
+    const options = readTextOptions(args[1], allowed);
+    if (!options || (typeof text !== "string" && args.length === 2))
+        return undefined;
+    return { method, text, ...options };
+}
+function readRole(args) {
+    const role = stringOf(args[0]);
+    if (role === undefined || args.length > 2)
+        return undefined;
+    const props = args.length === 2 ? readProps(args[1], ROLE_KEYS) : {};
+    if (!props)
         return undefined;
+    const call = { method: "getByRole", role };
+    if (props.name) {
+        const name = readTextMatcher(props.name);
+        if (name === undefined)
+            return undefined;
+        call.name = name;
+    }
+    if (props.exact) {
+        const exact = booleanOf(props.exact);
+        if (exact === undefined || (call.name && typeof call.name !== "string"))
+            return undefined;
+        call.exact = exact;
+    }
+    if (props.level) {
+        const level = integerOf(props.level);
+        if (level === undefined || level < 1)
+            return undefined;
+        call.level = level;
+    }
+    for (const key of TRISTATE) {
+        const node = props[key];
+        if (!node)
+            continue;
+        const value = stringOf(node) === "mixed" ? "mixed" : booleanOf(node);
+        if (value === undefined)
+            return undefined;
+        call[key] = value;
+    }
+    for (const key of FLAGS) {
+        const node = props[key];
+        if (!node)
+            continue;
+        const value = booleanOf(node);
+        if (value === undefined)
+            return undefined;
+        call[key] = value;
+    }
+    return call;
+}
+function readNarrowing(method, args) {
+    if (method === "first" || method === "last")
+        return args.length === 0 ? { method } : undefined;
+    if (method === "nth") {
+        const index = integerOf(args[0]);
+        return args.length === 1 && index !== undefined
+            ? { method, index }
+            : undefined;
+    }
+    const hasText = readProps(args[0], ["hasText"])?.hasText;
+    const text = readTextMatcher(hasText);
+    return method === "filter" && args.length === 1 && text !== undefined
+        ? { method, hasText: text }
+        : undefined;
+}
+function readCall(method, args) {
+    if (NARROWING.includes(method))
+        return readNarrowing(method, args);
     switch (method) {
         case "locator":
-            return args.length === 1 ? { method, xpath: first } : undefined;
         case "getByCss":
-            return args.length === 1 ? { method, css: first } : undefined;
-        case "getByTestId":
-            return args.length === 1 ? { method, testId: first } : undefined;
-        case "getByText":
-        case "getByLabel": {
-            if (args.length > 2)
-                return undefined;
-            const options = args.length === 2 ? readObject(args[1], ["match", "ignoreCase"]) : {};
-            if (!options)
+        case "getByTestId": {
+            const first = stringOf(args[0]);
+            if (first === undefined || args.length !== 1)
                 return undefined;
-            const { match, ignoreCase } = options;
-            if ((match !== undefined && match !== "full" && match !== "partial") ||
-                (ignoreCase !== undefined && typeof ignoreCase !== "boolean")) {
-                return undefined;
-            }
-            return {
-                method,
-                text: first,
-                ...(match !== undefined && { match: match }),
-                ...(ignoreCase !== undefined && { ignoreCase: ignoreCase }),
-            };
-        }
-        case "getByRole": {
-            if (args.length > 2)
-                return undefined;
-            const options = args.length === 2 ? readObject(args[1], ["name"]) : {};
-            if (!options ||
-                (options.name !== undefined && typeof options.name !== "string"))
-                return undefined;
-            return {
-                method,
-                role: first,
-                ...(options.name !== undefined && { name: options.name }),
-            };
+            return method === "locator"
+                ? { method, xpath: first }
+                : method === "getByCss"
+                    ? { method, css: first }
+                    : { method, testId: first };
         }
+        case "getByText":
+        case "getByLabel":
+            return readTextCall(method, args, [
+                "exact",
+                "match",
+                "ignoreCase",
+            ]);
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+            return readTextCall(method, args, ["exact"]);
+        case "getByRole":
+            return readRole(args);
         default:
             return undefined;
     }
@@ -60,7 +143,10 @@ function readChain(node) {
         calls.unshift(call);
         current = current.expression.expression;
     }
-    return ts.isIdentifier(current) && current.text === "page" && calls.length > 0
+    return ts.isIdentifier(current) &&
+        current.text === "page" &&
+        calls.length > 0 &&
+        !NARROWING.includes(calls[0].method)
         ? calls
         : undefined;
 }

package/dist/steps/parse/expectation.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import type { Expectation, PageExpectation, TextValue } from "../model.js";
+import type { Expectation, PageExpectation, TextMatcher, TextValue } from "../model.js";
 /** `env.NAME`, `secrets.NAME`, `inputs.NAME` (or `env["NAME"]` and so on) or a string literal */
 export declare function readValue(node: ts.Expression | undefined): TextValue | undefined;
 /** `/source/flags` */
@@ -7,6 +7,7 @@ export declare function readRegex(node: ts.Expression | undefined): {
     source: string;
     flags: string;
 } | undefined;
+export declare function readTextMatcher(node: ts.Expression | undefined): TextMatcher | undefined;
 /** The matchers that take `{ output }` as their last argument */
 export declare const OUTPUT_MATCHERS: readonly string[];
 export declare function readExpectation(matcher: string, args: readonly ts.Expression[]): Expectation | undefined;

package/dist/steps/parse/expectation.js

@@ -1,6 +1,26 @@
 import ts from "typescript";
 import { stringOf } from "./literals.js";
 const TEXT_MATCHERS = ["toHaveText", "toContainText", "toHaveValue"];
+/** The matchers that take no argument: a call with options (`{ visible: false }`, `{ timeout }`) is custom */
+const NO_ARGUMENT_MATCHERS = [
+    "toBeVisible",
+    "toBeHidden",
+    "toBeEnabled",
+    "toBeChecked",
+    "toBeFocused",
+    "toBeDisabled",
+    "toBeEditable",
+    "toBeAttached",
+    "toBeInViewport",
+    "toBeEmpty",
+];
+/** The matchers that take one text or RegExp; only `TEXT_MATCHERS` can also save an output */
+const TEXT_ARGUMENT_MATCHERS = [
+    ...TEXT_MATCHERS,
+    "toHaveId",
+    "toHaveAccessibleName",
+    "toHaveAccessibleDescription",
+];
 /** `env.NAME`, `secrets.NAME`, `inputs.NAME` (or `env["NAME"]` and so on) or a string literal */
 export function readValue(node) {
     if (!node)
@@ -37,7 +57,7 @@ export function readRegex(node) {
     const end = node.text.lastIndexOf("/");
     return { source: node.text.slice(1, end), flags: node.text.slice(end + 1) };
 }
-function readTextMatcher(node) {
+export function readTextMatcher(node) {
     if (!node)
         return undefined;
     const literal = stringOf(node);
@@ -52,11 +72,10 @@ export const OUTPUT_MATCHERS = [
     "toHaveAttribute",
 ];
 export function readExpectation(matcher, args) {
-    if (matcher === "toBeVisible" ||
-        matcher === "toBeHidden" ||
-        matcher === "toBeEnabled" ||
-        matcher === "toBeChecked")
-        return args.length === 0 ? { matcher } : undefined;
+    if (NO_ARGUMENT_MATCHERS.includes(matcher))
+        return args.length === 0
+            ? { matcher: matcher }
+            : undefined;
     if (matcher === "toHaveClass") {
         const expected = readTextMatcher(args[0]);
         return args.length === 1 && expected !== undefined
@@ -83,10 +102,13 @@ export function readExpectation(matcher, args) {
             ? { matcher, name, expected }
             : undefined;
     }
-    if (TEXT_MATCHERS.includes(matcher)) {
+    if (TEXT_ARGUMENT_MATCHERS.includes(matcher)) {
         const expected = readTextMatcher(args[0]);
         return args.length === 1 && expected !== undefined
-            ? { matcher: matcher, expected }
+            ? {
+                matcher: matcher,
+                expected,
+            }
             : undefined;
     }
     return undefined;

package/dist/steps/parse/literals.d.ts

@@ -1,4 +1,13 @@
 import ts from "typescript";
 export declare function stringOf(node: ts.Node | undefined): string | undefined;
+/** `true` or `false` */
+export declare function booleanOf(node: ts.Node | undefined): boolean | undefined;
+/** An integer literal, with a `-` in front when negative */
+export declare function integerOf(node: ts.Node | undefined): number | undefined;
 /** `{ key: literal, … }` with only the allowed keys, or undefined when it has anything else */
 export declare function readObject(node: ts.Node | undefined, allowed: readonly string[]): Record<string, string | boolean> | undefined;
+/**
+ * The values of `{ key: value, … }` as expressions, by key, or undefined when the object has a key that isn't
+ * allowed or isn't a plain name, a spread, a shorthand or a key twice
+ */
+export declare function readProps(node: ts.Node | undefined, allowed: readonly string[]): Record<string, ts.Expression> | undefined;

package/dist/steps/parse/literals.js

@@ -5,6 +5,30 @@ export function stringOf(node) {
         ? node.text
         : undefined;
 }
+/** `true` or `false` */
+export function booleanOf(node) {
+    if (node?.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (node?.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
+/** An integer literal, with a `-` in front when negative */
+export function integerOf(node) {
+    if (!node)
+        return undefined;
+    if (ts.isNumericLiteral(node)) {
+        const value = Number(node.text);
+        return Number.isInteger(value) ? value : undefined;
+    }
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)) {
+        const value = integerOf(node.operand);
+        return value === undefined || value === 0 ? undefined : -value;
+    }
+    return undefined;
+}
 /** `{ key: literal, … }` with only the allowed keys, or undefined when it has anything else */
 export function readObject(node, allowed) {
     if (!node || !ts.isObjectLiteralExpression(node))
@@ -26,3 +50,21 @@ export function readObject(node, allowed) {
     }
     return result;
 }
+/**
+ * The values of `{ key: value, … }` as expressions, by key, or undefined when the object has a key that isn't
+ * allowed or isn't a plain name, a spread, a shorthand or a key twice
+ */
+export function readProps(node, allowed) {
+    if (!node || !ts.isObjectLiteralExpression(node))
+        return undefined;
+    const props = {};
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name))
+            return undefined;
+        const name = property.name.text;
+        if (!allowed.includes(name) || name in props)
+            return undefined;
+        props[name] = property.initializer;
+    }
+    return props;
+}

package/dist/steps/parse/step.js

@@ -2,7 +2,7 @@ import ts from "typescript";
 import { readLocator } from "./call.js";
 import { OUTPUT_MATCHERS, readExpectation, readPageExpectation, readRegex, readValue, } from "./expectation.js";
 import { readFiles } from "./file-entry.js";
-import { readObject, stringOf } from "./literals.js";
+import { integerOf, readObject, readProps, stringOf } from "./literals.js";
 /**
  * The name in a trailing `{ output: "name" }`: undefined without one, null when the argument is there but
  * isn't exactly that
@@ -53,6 +53,25 @@ function readLocatorExpect(subject, negated, matcher, args) {
         }
         : undefined;
 }
+/** The actions that take a locator and nothing else */
+const ACTIONS = ["check", "uncheck", "hover", "dblclick", "clear"];
+/** `"value or label"`, `{ value }`, `{ label }` or `{ index }`: exactly one key; anything else is undefined */
+function readSelectChoice(node) {
+    const text = stringOf(node);
+    if (text !== undefined)
+        return text;
+    const props = readProps(node, ["value", "label", "index"]);
+    const keys = Object.keys(props ?? {});
+    if (!props || keys.length !== 1)
+        return undefined;
+    const [key] = keys;
+    if (key === "index") {
+        const index = integerOf(props.index);
+        return index !== undefined && index >= 0 ? { index } : undefined;
+    }
+    const value = stringOf(props[key]);
+    return value === undefined ? undefined : { [key]: value };
+}
 /** The step a statement stands for, or undefined when it is outside the recorder's set */
 export function readStep(statement) {
     if (!ts.isExpressionStatement(statement) ||
@@ -117,6 +136,14 @@ export function readStep(statement) {
         return undefined;
     if (name.text === "click" && args.length === 0)
         return { kind: "click", locator };
+    if (ACTIONS.includes(name.text) && args.length === 0)
+        return { kind: name.text, locator };
+    if (name.text === "selectOption" && args.length === 1) {
+        const option = readSelectChoice(args[0]);
+        return option === undefined
+            ? undefined
+            : { kind: "selectOption", locator, option };
+    }
     if (name.text === "press" && args.length === 1) {
         const key = stringOf(args[0]);
         return key === undefined ? undefined : { kind: "press", locator, key };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {