@itmetsam/samurai-framework 0.2.2 → 0.2.3

package/dist/locator/locator.d.ts

@@ -163,6 +163,14 @@ export default class Locator {
     isEditable(): Promise<boolean>;
     /** Wait for certain time (ms). Default: 300ms  */
     wait(duration?: number): Promise<void>;
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    press(key: string, options?: ActionOptions): Promise<void>;
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     fill(value: string, options?: ActionOptions): Promise<void>;
 }

package/dist/locator/locator.js

@@ -42,7 +42,25 @@ const FILL_CHECKS = [
     "editable",
     "hit target",
 ];
+const PRESS_CHECKS = ["attached", "visible", "enabled"];
 const ATTACHED_ONLY = ["attached"];
+/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
+const NAMED_KEYS = {
+    Backspace: "\uE003",
+    Tab: "\uE004",
+    Enter: "\uE007",
+    Escape: "\uE00C",
+    Space: " ",
+    ArrowLeft: "\uE012",
+    ArrowUp: "\uE013",
+    ArrowRight: "\uE014",
+    ArrowDown: "\uE015",
+    Delete: "\uE017",
+    Home: "\uE011",
+    End: "\uE010",
+    PageUp: "\uE00E",
+    PageDown: "\uE00F",
+};
 /** Unicode code point WebDriver uses for the Backspace key */
 const BACKSPACE = "";
 export default class Locator {
@@ -556,6 +574,34 @@ export default class Locator {
             ],
         });
     }
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    async press(key, options) {
+        const code = NAMED_KEYS[key] ?? (Array.from(key).length === 1 ? key : "");
+        if (code === "") {
+            throw new Error(`press(): unknown key "${key}". Use one of ${Object.keys(NAMED_KEYS).join(", ")} or a single character`);
+        }
+        await this.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+        await this.callOnElement(undefined, `el.focus();`);
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    type: "key",
+                    id: "samurai-keyboard",
+                    actions: [
+                        { type: "keyDown", value: code },
+                        { type: "keyUp", value: code },
+                    ],
+                },
+            ],
+        });
+    }
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     async fill(value, options) {
         const state = await this.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);

package/dist/recorder/capture.d.ts

@@ -6,6 +6,8 @@
  *   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: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ *   click or typing, which are reported as such).
  * - `{ 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.
  *

package/dist/recorder/capture.js

@@ -8,6 +8,8 @@ const OFF_KEY = "samurai.recorder.off";
  *   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: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ *   click or typing, which are reported as such).
  * - `{ 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.
  *
@@ -184,6 +186,18 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     });
   }, true);
 
+  // Enter, Tab and Escape change what the page does next (an Enter adds a todo and clears the field), so they are steps
+  const RECORDED_KEYS = ["Enter", "Tab", "Escape"];
+  // Enter on these is a click, which is recorded as one
+  const ACTIVATES = "a[href],button,summary,select,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio]";
+  document.addEventListener("keydown", (event) => {
+    if (off() || !event.isTrusted || event.isComposing || event.ctrlKey || event.altKey || event.metaKey || event.shiftKey) return;
+    if (RECORDED_KEYS.indexOf(event.key) < 0 || !(event.target instanceof Element)) return;
+    const el = event.target;
+    if (event.key === "Enter" && (el.closest(ACTIVATES) || el.tagName === "TEXTAREA" || el.isContentEditable)) return;
+    report({ type: "press", target: el, candidates: candidatesOf(el), pressed: event.key });
+  }, true);
+
   document.addEventListener("mousemove", (event) => {
     if (off() || !event.altKey || !(event.target instanceof Element) || event.target === outlined) return;
     unhighlight();

package/dist/recorder/normalise.d.ts

@@ -22,6 +22,11 @@ export type Observation = {
     value?: string;
     secret?: boolean;
     secretName?: string;
+} | {
+    type: "press";
+    key: string;
+    locator: LocatorSpec;
+    pressed: string;
 } | {
     type: "assert";
     key: string;

package/dist/recorder/normalise.js

@@ -60,6 +60,18 @@ export class Normaliser {
             this.lastAction = at;
             return [this.insert({ kind: "click", locator: observation.locator })];
         }
+        if (observation.type === "press") {
+            // 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;
+            this.lastAction = at;
+            return [
+                this.insert({
+                    kind: "press",
+                    locator: observation.locator,
+                    key: observation.pressed,
+                }),
+            ];
+        }
         if (observation.type === "assert") {
             this.lastFill = undefined;
             return [

package/dist/recorder/recorder.js

@@ -99,24 +99,26 @@ export class Recorder {
         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,
-                    }),
-                };
+            : 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,
+                        }),
+                    };
         this.emit(this.normaliser.observe(observation, Date.now()));
     }
     async release() {

package/dist/steps/emit.js

@@ -63,6 +63,8 @@ export function stepToSource(step) {
             return `await ${locatorToSource(step.locator)}.click();`;
         case "fill":
             return `await ${locatorToSource(step.locator)}.fill(${valueToSource(step.value)});`;
+        case "press":
+            return `await ${locatorToSource(step.locator)}.press(${str(step.key)});`;
         case "expect":
             return `await expect(${locatorToSource(step.locator)})${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
         case "waitForNetworkIdle":

package/dist/steps/model.d.ts

@@ -75,6 +75,12 @@ export type Step = {
     locator: LocatorSpec;
     not: boolean;
     expectation: Expectation;
+}
+/** A key pressed while the element has focus, e.g. `Enter` to submit a field. Named as Playwright names keys */
+ | {
+    kind: "press";
+    locator: LocatorSpec;
+    key: string;
 } | {
     kind: "waitForNetworkIdle";
 }

package/dist/steps/parse.js

@@ -214,6 +214,10 @@ function readStep(statement) {
         return undefined;
     if (name.text === "click" && args.length === 0)
         return { kind: "click", locator };
+    if (name.text === "press" && args.length === 1) {
+        const key = stringOf(args[0]);
+        return key === undefined ? undefined : { kind: "press", locator, key };
+    }
     if (name.text === "fill" && args.length === 1) {
         const value = readValue(args[0]);
         return value ? { kind: "fill", locator, value } : undefined;

package/package.json

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