@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/config/storage-state-file.d.ts

@@ -0,0 +1,3 @@
+import type { StorageState } from "../types/use.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `<who>: what is wrong` (`use()` unless told otherwise). */
+export declare function loadStorageState(source: string | StorageState, baseDir: string, who?: string): StorageState;

package/dist/config/storage-state-file.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { checkStorageStateObject } from "./use-options.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `<who>: what is wrong` (`use()` unless told otherwise). */
+export function loadStorageState(source, baseDir, who = "use()") {
+    if (typeof source !== "string")
+        return source;
+    const file = path.resolve(baseDir, source);
+    let state;
+    try {
+        state = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${who}: storageState file ${JSON.stringify(source)} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof state !== "object" || state === null || Array.isArray(state))
+        throw new Error(`${who}: storageState file ${JSON.stringify(source)} must hold an object`);
+    checkStorageStateObject(state);
+    return state;
+}

package/dist/config/use-options.d.ts

@@ -1,5 +1,7 @@
 import type { SamuraiTestConfig } from "../types/config.js";
 import type { UseOptions } from "../types/use.js";
+/** The options of `use`: config, group, `test.use()` and (those that can change at run time) `page.use()` */
+export declare const USE_OPTION_NAMES: readonly string[];
 /**
  * Checks the options of `test.use()` or of the config's `use` and returns them. The config's `use` also holds
  * options that are not these (`viewport`, `headless`, ...), so it passes `allowOthers`; `test.use()` refuses
@@ -9,7 +11,7 @@ export declare function validateUseOptions(options: unknown, allowOthers?: boole
 /** Checks a storage state object, whether it came from the options or from a file */
 export declare function checkStorageStateObject(state: Record<string, unknown>): void;
 /** The options after `layers` are applied in order: a later layer wins, key by key */
-export declare function mergeUse(layers: readonly UseOptions[]): UseOptions;
+export declare function mergeUse<T extends UseOptions>(layers: readonly T[]): T;
 /** Checks the new options of a config's `use` */
 export declare function validateUseConfig(config: SamuraiTestConfig): void;
 /** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */

package/dist/config/use-options.js

@@ -1,7 +1,13 @@
-const NAMES = [
+import { checkFixtureUse, isFixtureUseKey } from "./fixture-use.js";
+/** The options of `use`: config, group, `test.use()` and (those that can change at run time) `page.use()` */
+export const USE_OPTION_NAMES = [
     "locale",
-    "timezoneId",
+    "timezone",
     "userAgent",
+    "geolocation",
+    "offline",
+    "orientation",
+    "screen",
     "javaScriptEnabled",
     "acceptInsecureCerts",
     "hasTouch",
@@ -10,12 +16,20 @@ const NAMES = [
     "extraHTTPHeaders",
     "colorScheme",
 ];
-const BOOLEANS = [
-    "javaScriptEnabled",
-    "acceptInsecureCerts",
-    "hasTouch",
-    "isMobile",
+/** A name that was in use once, and the one that replaced it: refused with a message that says which */
+const RENAMED = {
+    timezoneId: "timezone",
+    touch: "hasTouch",
+};
+const ORIENTATIONS = [
+    "portrait-primary",
+    "portrait-secondary",
+    "landscape-primary",
+    "landscape-secondary",
 ];
+/** These may be `null` (the real value back) */
+const NULLABLE_BOOLEANS = ["javaScriptEnabled", "hasTouch", "offline"];
+const BOOLEANS = ["acceptInsecureCerts", "isMobile"];
 const COLOR_SCHEMES = ["light", "dark", "no-preference"];
 const HEADER_NAME = /^[\w!#$%&'*+.^`|~-]+$/;
 const fail = (problem) => {
@@ -30,17 +44,32 @@ const isObject = (value) => typeof value === "object" && value !== null && !Arra
 export function validateUseOptions(options, allowOthers = false) {
     if (!isObject(options))
         return fail("the options must be an object");
-    for (const key of Object.keys(options))
-        if (!allowOthers && !NAMES.includes(key))
+    for (const key of Object.keys(options)) {
+        const renamed = RENAMED[key];
+        if (renamed !== undefined)
+            fail(`unknown option "${key}"; use "${renamed}"`);
+        if (!allowOthers &&
+            !USE_OPTION_NAMES.includes(key) &&
+            !isFixtureUseKey(key))
             fail(`unknown option "${key}"`);
+    }
+    checkFixtureUse(options);
     const use = options;
     for (const name of BOOLEANS)
         if (use[name] !== undefined && typeof use[name] !== "boolean")
             fail(`${name} must be true or false, got ${JSON.stringify(use[name])}`);
-    checkLocale(use.locale);
-    checkTimezone(use.timezoneId);
-    if (use.userAgent !== undefined && !nonEmpty(use.userAgent))
+    for (const name of NULLABLE_BOOLEANS)
+        if (use[name] != null && typeof use[name] !== "boolean")
+            fail(`${name} must be true, false or null, got ${JSON.stringify(use[name])}`);
+    if (use.locale !== null)
+        checkLocale(use.locale);
+    if (use.timezone !== null)
+        checkTimezone(use.timezone);
+    if (use.userAgent != null && !nonEmpty(use.userAgent))
         fail("userAgent must be a non-empty string");
+    checkGeolocation(use.geolocation);
+    checkOrientation(use.orientation);
+    checkScreen(use.screen);
     if (use.colorScheme !== undefined && !COLOR_SCHEMES.includes(use.colorScheme))
         fail(`colorScheme must be "light", "dark" or "no-preference", got ${JSON.stringify(use.colorScheme)}`);
     checkHeaders(use.extraHTTPHeaders);
@@ -68,9 +97,40 @@ function checkTimezone(timezone) {
         new Intl.DateTimeFormat(undefined, { timeZone: timezone });
     }
     catch {
-        fail(`unknown timezoneId ${JSON.stringify(timezone)}`);
+        fail(`unknown timezone ${JSON.stringify(timezone)}`);
     }
 }
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
+function checkGeolocation(place) {
+    if (place === undefined || place === null)
+        return;
+    if (!isObject(place))
+        return fail("geolocation must be { latitude, longitude } or null");
+    const { latitude, longitude, accuracy } = place;
+    if (!isNumber(latitude) || latitude < -90 || latitude > 90)
+        fail("latitude must be between -90 and 90");
+    if (!isNumber(longitude) || longitude < -180 || longitude > 180)
+        fail("longitude must be between -180 and 180");
+    if (accuracy !== undefined && (!isNumber(accuracy) || accuracy < 0))
+        fail("accuracy must be 0 or more");
+}
+function checkOrientation(orientation) {
+    if (orientation === undefined || orientation === null)
+        return;
+    const type = orientation === "portrait" || orientation === "landscape"
+        ? `${orientation}-primary`
+        : orientation;
+    if (!ORIENTATIONS.includes(type))
+        fail(`unknown orientation ${JSON.stringify(orientation)}`);
+}
+function checkScreen(screen) {
+    if (screen === undefined || screen === null)
+        return;
+    if (!isObject(screen) ||
+        !(isPositiveInteger(screen.width) && isPositiveInteger(screen.height)))
+        fail("screen width and height must be positive integers");
+}
 function checkHeaders(headers) {
     if (headers === undefined)
         return;
@@ -124,5 +184,5 @@ export function validateUseConfig(config) {
 }
 /** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */
 export function useOptionsOf(configUse) {
-    return Object.fromEntries(Object.entries(configUse ?? {}).filter(([key]) => NAMES.includes(key)));
+    return Object.fromEntries(Object.entries(configUse ?? {}).filter(([key]) => USE_OPTION_NAMES.includes(key)));
 }

package/dist/config/web-server-options.d.ts

@@ -0,0 +1,7 @@
+import type { SamuraiTestConfig, WebServerConfig } from "../types/config.js";
+export declare const DEFAULT_WEB_SERVER_TIMEOUT = 60000;
+export declare const DEFAULT_GRACEFUL_TIMEOUT = 5000;
+/** The config's `webServer` as a list (empty when there is none). Call after validation */
+export declare function webServersOf(config: SamuraiTestConfig): WebServerConfig[];
+/** Checks the `webServer`, `globalSetup` and `globalTeardown` keys of a config. Throws `config.<key>: what is wrong` */
+export declare function validateWebServerConfig(config: SamuraiTestConfig): void;

package/dist/config/web-server-options.js

@@ -0,0 +1,111 @@
+export const DEFAULT_WEB_SERVER_TIMEOUT = 60_000;
+export const DEFAULT_GRACEFUL_TIMEOUT = 5_000;
+const KEYS = [
+    "command",
+    "url",
+    "port",
+    "cwd",
+    "env",
+    "timeout",
+    "reuseExistingServer",
+    "stdout",
+    "stderr",
+    "ignoreHTTPSErrors",
+    "gracefulShutdown",
+];
+const STREAMS = ["pipe", "ignore"];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fail = (where, problem) => {
+    throw new Error(`${where}: ${problem}`);
+};
+/** The config's `webServer` as a list (empty when there is none). Call after validation */
+export function webServersOf(config) {
+    const { webServer } = config;
+    if (webServer === undefined)
+        return [];
+    return Array.isArray(webServer) ? webServer : [webServer];
+}
+/** Checks the `webServer`, `globalSetup` and `globalTeardown` keys of a config. Throws `config.<key>: what is wrong` */
+export function validateWebServerConfig(config) {
+    const { webServer } = config;
+    if (webServer !== undefined) {
+        if (Array.isArray(webServer)) {
+            if (webServer.length === 0)
+                fail("config.webServer", "the list must not be empty");
+            webServer.forEach((server, index) => checkServer(server, `config.webServer[${index}]`));
+        }
+        else
+            checkServer(webServer, "config.webServer");
+    }
+    for (const key of ["globalSetup", "globalTeardown"]) {
+        const hook = config[key];
+        if (hook !== undefined &&
+            typeof hook !== "function" &&
+            (typeof hook !== "string" || hook === ""))
+            fail(`config.${key}`, "must be a module path or a function");
+    }
+}
+function checkServer(server, where) {
+    if (!isObject(server))
+        return fail(where, "must be an object");
+    for (const key of Object.keys(server))
+        if (!KEYS.includes(key))
+            fail(where, `unknown key "${key}"`);
+    const s = server;
+    if (typeof s.command !== "string" || s.command.trim() === "")
+        fail(`${where}.command`, "must be a non-empty string");
+    if ((s.url === undefined) === (s.port === undefined))
+        fail(where, "give either url or port");
+    if (s.url !== undefined)
+        checkUrl(s.url, `${where}.url`);
+    if (s.port !== undefined &&
+        !(Number.isInteger(s.port) && s.port >= 1 && s.port <= 65535))
+        fail(`${where}.port`, `must be a whole number from 1 to 65535`);
+    if (s.cwd !== undefined && (typeof s.cwd !== "string" || s.cwd === ""))
+        fail(`${where}.cwd`, "must be a non-empty string");
+    if (s.env !== undefined) {
+        if (!isObject(s.env))
+            fail(`${where}.env`, "must be an object of names and string values");
+        for (const [name, value] of Object.entries(s.env))
+            if (typeof value !== "string")
+                fail(`${where}.env`, `"${name}" must be a string`);
+    }
+    if (s.timeout !== undefined &&
+        !(typeof s.timeout === "number" &&
+            Number.isFinite(s.timeout) &&
+            s.timeout > 0))
+        fail(`${where}.timeout`, "must be a positive number of milliseconds");
+    for (const key of ["reuseExistingServer", "ignoreHTTPSErrors"])
+        if (s[key] !== undefined && typeof s[key] !== "boolean")
+            fail(`${where}.${key}`, "must be true or false");
+    for (const key of ["stdout", "stderr"])
+        if (s[key] !== undefined && !STREAMS.includes(s[key]))
+            fail(`${where}.${key}`, `must be "pipe" or "ignore"`);
+    if (s.gracefulShutdown !== undefined)
+        checkGraceful(s.gracefulShutdown, where);
+}
+function checkUrl(url, where) {
+    try {
+        if (typeof url !== "string")
+            throw new TypeError();
+        const protocol = new URL(url).protocol;
+        if (protocol !== "http:" && protocol !== "https:")
+            throw new TypeError();
+    }
+    catch {
+        fail(where, "must be an http or https URL");
+    }
+}
+function checkGraceful(graceful, where) {
+    if (!isObject(graceful))
+        return fail(`${where}.gracefulShutdown`, "must be an object");
+    for (const key of Object.keys(graceful))
+        if (key !== "signal" && key !== "timeout")
+            fail(`${where}.gracefulShutdown`, `unknown key "${key}"`);
+    const { signal, timeout } = graceful;
+    if (signal !== undefined && signal !== "SIGTERM" && signal !== "SIGINT")
+        fail(`${where}.gracefulShutdown.signal`, `must be "SIGTERM" or "SIGINT"`);
+    if (timeout !== undefined &&
+        !(typeof timeout === "number" && Number.isFinite(timeout) && timeout >= 0))
+        fail(`${where}.gracefulShutdown.timeout`, "must be a number of milliseconds, 0 or more");
+}

package/dist/locator/check-actions.js

@@ -1,5 +1,5 @@
 import { callOnExistingElement } from "./element-access.js";
-import { clickRect } from "./input-actions.js";
+import { clickRect } from "./pointer-actions.js";
 import { ATTACHED_ONLY, CLICK_CHECKS } from "./page-scripts.js";
 /** Body run in the page as `(el) => { ... }`: what kind of control the element is, and whether it is checked */
 const CONTROL_INFO_BODY = `

package/dist/locator/drag-actions.d.ts

@@ -0,0 +1,17 @@
+import type { ActionOptions } from "./actionability.js";
+import type { ElementAccess } from "./element-access.js";
+import { type Point } from "./pointer-actions.js";
+export interface DragOptions extends ActionOptions {
+    /** Where on the dragged element to press: pixels from its top left corner (default: the centre) */
+    sourcePosition?: Point;
+    /** Where on the target to release (default: the centre) */
+    targetPosition?: Point;
+    /** Pointer moves between the two points (default 10) */
+    steps?: number;
+}
+/**
+ * Presses on the element, moves to `target` in steps and releases there, with real pointer input. Both ends
+ * wait like a click does. Chrome runs a real HTML5 drag; Firefox starts one but never drops it from
+ * synthetic pointer input, so the drop (and `dragend`) are then fired as synthetic events (`isTrusted` false).
+ */
+export declare function dragElement(access: ElementAccess, target: ElementAccess, options?: DragOptions): Promise<void>;

package/dist/locator/drag-actions.js

@@ -0,0 +1,80 @@
+import { pointAtElement, } from "./pointer-element-actions.js";
+import { HOVER_CHECKS, CLICK_CHECKS } from "./page-scripts.js";
+import { pointerDrag } from "./pointer-actions.js";
+const DEFAULT_STEPS = 10;
+const STATE = `globalThis[Symbol.for("samurai.drag")]`;
+/** Starts watching the drag events of the document, to tell afterwards how far a native drag got */
+const WATCH_DRAG = `() => {
+  const state = { started: false, dropped: false, data: [], off: [] };
+  const on = (target, type, fn, capture) => {
+    target.addEventListener(type, fn, capture);
+    state.off.push(() => target.removeEventListener(type, fn, capture));
+  };
+  on(document, "dragstart", () => { state.started = true; }, true);
+  on(document, "drop", () => { state.dropped = true; }, true);
+  // Bubbling to the window comes after the page's own dragstart handlers, so what they put in the data is there
+  on(window, "dragstart", (event) => {
+    const dt = event.dataTransfer;
+    for (const type of dt ? Array.from(dt.types) : []) {
+      if (type !== "Files") state.data.push([type, dt.getData(type)]);
+    }
+  }, false);
+  ${STATE} = state;
+}`;
+/**
+ * Stops watching. When the browser began a native drag but never dropped (Firefox does this with
+ * synthetic pointer input), or the source is \`draggable\` and no drag began, fires the rest of the sequence as
+ * synthetic events with a DataTransfer that carries what the page's dragstart handler stored.
+ */
+const FINISH_DRAG = `(source, target, from, to, moved) => {
+  const state = ${STATE};
+  delete ${STATE};
+  if (!state) return;
+  state.off.forEach((off) => off());
+  if (state.dropped || !moved) return;
+  if (!state.started && !source.closest('[draggable="true"]')) return;
+  const data = new DataTransfer();
+  for (const [type, value] of state.data) data.setData(type, value);
+  const fire = (el, type, at) => el.dispatchEvent(new DragEvent(type, {
+    bubbles: true, cancelable: true, composed: true, dataTransfer: data, clientX: at.x, clientY: at.y,
+  }));
+  if (!state.started && !fire(source, "dragstart", from)) return;
+  if (!state.started) fire(target, "dragenter", to);
+  // A drop is only allowed where dragover was cancelled, as in a real drag
+  if (fire(target, "dragover", to)) { fire(source, "dragend", to); return; }
+  fire(target, "drop", to);
+  fire(source, "dragend", to);
+}`;
+/**
+ * Presses on the element, moves to `target` in steps and releases there, with real pointer input. Both ends
+ * wait like a click does. Chrome runs a real HTML5 drag; Firefox starts one but never drops it from
+ * synthetic pointer input, so the drop (and `dragend`) are then fired as synthetic events (`isTrusted` false).
+ */
+export async function dragElement(access, target, options = {}) {
+    const { sourcePosition, targetPosition, steps = DEFAULT_STEPS, ...wait } = options;
+    if (!Number.isInteger(steps) || steps < 1) {
+        throw new Error("dragTo(): steps must be a whole number, 1 or more");
+    }
+    const sourceOptions = {
+        ...wait,
+        ...(sourcePosition && { position: sourcePosition }),
+    };
+    const targetOptions = {
+        ...wait,
+        ...(targetPosition && { position: targetPosition }),
+    };
+    // The target first: scrolling it into view may move the source, which is probed last
+    const to = await pointAtElement(target, "dragTo", HOVER_CHECKS, targetOptions);
+    const from = await pointAtElement(access, "dragTo", CLICK_CHECKS, sourceOptions);
+    const source = await access.requireElement();
+    const destination = await target.requireElement();
+    await access.call(WATCH_DRAG, []);
+    let moved = false;
+    try {
+        await pointerDrag(access.connector, access.contextId, from, to, steps);
+        moved = true;
+    }
+    finally {
+        await access.call(FINISH_DRAG, [source, destination, from, to, moved]);
+    }
+}

package/dist/locator/element-actions.d.ts

@@ -1,16 +1,22 @@
 import { type ElementScreenshotOptions } from "../browser/screenshot.js";
 import type { ActionOptions } from "./actionability.js";
 import { type ElementAccess } from "./element-access.js";
-/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
-export declare function clickElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
 /** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
 export declare function screenshotElement(access: ElementAccess, options?: ElementScreenshotOptions & {
     timeout?: number;
 }): Promise<Buffer>;
 /** Waits until the element is attached, then focuses it */
 export declare function focusElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
-/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
-export declare function pressOnElement(access: ElementAccess, key: string, options?: ActionOptions): Promise<void>;
+/** Focuses the element and presses `key` with real keyboard input; `key` can be a chord such as `Control+a` */
+export declare function pressOnElement(access: ElementAccess, key: string, options?: ActionOptions & {
+    delay?: number;
+}): Promise<void>;
+/** Focuses the element and types `text` into it one key press at a time, `delay` ms apart */
+export declare function pressSequentially(access: ElementAccess, text: string, options?: ActionOptions & {
+    delay?: number;
+}): Promise<void>;
+/** Empties an input, textarea or editable element, as `fill("")` does */
+export declare function clearElement(access: ElementAccess, 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 */
 export declare function fillElement(access: ElementAccess, value: string, options?: ActionOptions & {
     output?: string;

package/dist/locator/element-actions.js

@@ -1,14 +1,11 @@
 import { bindOutput } from "../wait/output-sink.js";
 import { takeScreenshot, } from "../browser/screenshot.js";
 import { callOnElement, callOnExistingElement, requireElement, } from "./element-access.js";
-import { clickRect, DEFAULT_PAUSE_MS, NAMED_KEYS, pause, pressKey, typeText, } from "./input-actions.js";
-import { ATTACHED_ONLY, CLICK_CHECKS, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, } from "./page-scripts.js";
-/** Waits until the element is attached, visible, stable, enabled and not covered, then clicks its centre with real pointer input */
-export async function clickElement(access, options) {
-    const state = await access.waitForActionable("click", CLICK_CHECKS, { scroll: true, hitTest: true }, options);
-    // "attached" is always required, so the box is present
-    await clickRect(access.connector, access.contextId, state.box);
-}
+import { clickRect } from "./pointer-actions.js";
+import { DEFAULT_PAUSE_MS, pause, typeText } from "./input-actions.js";
+import { chordSteps, performKeys, textSteps } from "./key-actions.js";
+import { NAMED_KEYS, parseKeyChord } from "./key-map.js";
+import { ATTACHED_ONLY, FILL_CHECKS, PRESS_CHECKS, SCREENSHOT_CHECKS, } from "./page-scripts.js";
 /** Takes a screenshot of just the element, after scrolling it into view and waiting until it is attached and visible */
 export async function screenshotElement(access, options = {}) {
     const { timeout, ...capture } = options;
@@ -23,15 +20,25 @@ export async function focusElement(access, options) {
     await access.waitForActionable("focus", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
     await callOnExistingElement(access, `el.focus();`);
 }
-/** Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input */
-export async function pressOnElement(access, 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 access.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+/** Waits until the element is attached, visible and enabled and focuses it; the keys then go to the page's keyboard */
+async function focusForKeys(access, method, options) {
+    await access.waitForActionable(method, PRESS_CHECKS, { scroll: true, hitTest: false }, options);
     await callOnElement(access, undefined, `el.focus();`);
-    await pressKey(access.connector, access.contextId, code);
+}
+/** Focuses the element and presses `key` with real keyboard input; `key` can be a chord such as `Control+a` */
+export async function pressOnElement(access, key, options) {
+    const chord = parseKeyChord(key, "press");
+    await focusForKeys(access, "press", options);
+    await performKeys(access.connector, access.contextId, chordSteps(chord, options?.delay));
+}
+/** Focuses the element and types `text` into it one key press at a time, `delay` ms apart */
+export async function pressSequentially(access, text, options) {
+    await focusForKeys(access, "pressSequentially", options);
+    await performKeys(access.connector, access.contextId, textSteps(text, options?.delay));
+}
+/** Empties an input, textarea or editable element, as `fill("")` does */
+export async function clearElement(access, options) {
+    await fillElement(access, "", options);
 }
 /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
 export async function fillElement(access, value, options) {

package/dist/locator/element-state.d.ts

@@ -22,6 +22,11 @@ export interface ProbeOptions {
     scroll: boolean;
     /** Check which element receives a click at the element's centre */
     hitTest: boolean;
+    /** Where to check the hit: this far from the element's top left corner; the centre without it */
+    at?: {
+        x: number;
+        y: number;
+    };
     /**
      * Probe a checkbox, radio or switch the way a user reaches it: opacity 0 does not hide it, and a click on
      * one of its labels counts as hitting it (`control-probe.ts`). Only the check actions set this

package/dist/locator/element-state.js

@@ -46,7 +46,8 @@ export const PROBE_ELEMENT = `(el, options) => {
   const editable = Boolean(enabled && !el.readOnly && typeable);
   let hitTarget = null;
   if (options.hitTest) {
-    const top = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    const at = options.at || { x: rect.width / 2, y: rect.height / 2 };
+    const top = document.elementFromPoint(rect.left + at.x, rect.top + at.y);
     hitTarget = !top ? "nothing"
       : top === el || el.contains(top) ? "self"
       : top.tagName.toLowerCase() + (top.id ? "#" + top.id : "") +

package/dist/locator/event-actions.d.ts

@@ -0,0 +1,10 @@
+import type { ActionOptions } from "./actionability.js";
+import { type ElementAccess } from "./element-access.js";
+/** Waits until the element is attached, then removes focus from it */
+export declare function blurElement(access: ElementAccess, options?: ActionOptions): Promise<void>;
+/**
+ * Waits until the element is attached, then fires a synthetic event of `type` at it (no scrolling, visibility or
+ * enabled checks, as with a user it would not be reached). The event class follows the type; `eventInit`
+ * (plain data) is merged over `bubbles`, `cancelable` and `composed`, which are all true.
+ */
+export declare function dispatchEventOn(access: ElementAccess, type: string, eventInit?: Record<string, unknown>, options?: ActionOptions): Promise<void>;

package/dist/locator/event-actions.js

@@ -0,0 +1,81 @@
+import { callOnExistingElement } from "./element-access.js";
+import { ATTACHED_ONLY } from "./page-scripts.js";
+/** Waits until the element is attached, then removes focus from it */
+export async function blurElement(access, options) {
+    await access.waitForActionable("blur", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
+    await callOnExistingElement(access, `el.blur();`);
+}
+// The event interface each type is made with; any other type is a plain Event
+const EVENT_CLASSES = {
+    MouseEvent: [
+        "click",
+        "dblclick",
+        "auxclick",
+        "contextmenu",
+        "mousedown",
+        "mouseup",
+        "mousemove",
+        "mouseover",
+        "mouseout",
+        "mouseenter",
+        "mouseleave",
+    ],
+    PointerEvent: [
+        "pointerdown",
+        "pointerup",
+        "pointermove",
+        "pointerover",
+        "pointerout",
+        "pointerenter",
+        "pointerleave",
+        "pointercancel",
+        "gotpointercapture",
+        "lostpointercapture",
+    ],
+    KeyboardEvent: ["keydown", "keyup", "keypress"],
+    FocusEvent: ["focus", "blur", "focusin", "focusout"],
+    InputEvent: ["input", "beforeinput"],
+    WheelEvent: ["wheel"],
+    DragEvent: [
+        "drag",
+        "dragstart",
+        "dragend",
+        "dragenter",
+        "dragover",
+        "dragleave",
+        "drop",
+    ],
+    CompositionEvent: ["compositionstart", "compositionupdate", "compositionend"],
+    TouchEvent: ["touchstart", "touchend", "touchmove", "touchcancel"],
+    AnimationEvent: ["animationstart", "animationend", "animationiteration"],
+    TransitionEvent: [
+        "transitionrun",
+        "transitionstart",
+        "transitionend",
+        "transitioncancel",
+    ],
+};
+/** Body run in the page as `(el, type, init, classes) => { ... }`: builds the event by its type and fires it at `el` */
+const DISPATCH_BODY = `
+  const name = Object.keys(classes).find((key) => classes[key].includes(type));
+  const Ctor = (name && globalThis[name]) || Event;
+  const init = Object.assign({ bubbles: true, cancelable: true, composed: true }, eventInit);
+  if (name === "DragEvent" && !init.dataTransfer) init.dataTransfer = new DataTransfer();
+  el.dispatchEvent(new Ctor(type, init));`;
+/**
+ * Waits until the element is attached, then fires a synthetic event of `type` at it (no scrolling, visibility or
+ * enabled checks, as with a user it would not be reached). The event class follows the type; `eventInit`
+ * (plain data) is merged over `bubbles`, `cancelable` and `composed`, which are all true.
+ */
+export async function dispatchEventOn(access, type, eventInit = {}, options) {
+    if (type === "")
+        throw new Error("dispatchEvent(): type must not be empty");
+    await access.waitForActionable("dispatchEvent", ATTACHED_ONLY, { scroll: false, hitTest: false }, options);
+    const el = await access.requireElement();
+    await access.call(`(el, type, eventInit, classes) => {${DISPATCH_BODY}}`, [
+        el,
+        type,
+        eventInit,
+        EVENT_CLASSES,
+    ]);
+}

package/dist/locator/input-actions.d.ts

@@ -1,18 +1,9 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 /** How long `wait()` pauses when no duration is given (ms) */
 export declare const DEFAULT_PAUSE_MS = 300;
-/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
-export declare const NAMED_KEYS: Readonly<Record<string, string>>;
-/** Clicks the centre of `rect` (viewport pixels) with real pointer input */
-export declare function clickRect(connector: BiDiConnector, context: string, rect: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}): Promise<void>;
+export declare const POINTER_ID = "samurai-pointer";
+export declare const KEYBOARD_ID = "samurai-keyboard";
 /** Pauses the input queue for `duration` ms */
 export declare function pause(connector: BiDiConnector, context: string, duration: number): Promise<void>;
-/** Presses and releases one key, given as its WebDriver code point or a character */
-export declare function pressKey(connector: BiDiConnector, context: string, code: string): Promise<void>;
 /** Types `text` one character at a time (each pressed and released) */
 export declare function typeText(connector: BiDiConnector, context: string, text: string): Promise<void>;