@itmetsam/samurai-framework 0.22.0 → 0.22.2

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 };