@itmetsam/samurai-framework 0.21.5 → 0.22.0

package/dist/config/config.js

@@ -2,10 +2,13 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateGroupUse } from "./group-use.js";
 import { validateUseConfig } from "./use-options.js";
 import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
+import { validateFullyParallelConfig } from "./fully-parallel.js";
 import { validateWorkersConfig } from "./workers.js";
+import { validateWebServerConfig } from "./web-server-options.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
 export function setActiveProject(project) {
@@ -31,7 +34,10 @@ export function validateConfig(config) {
     validateWorkersConfig(config);
     validateForbidOnlyConfig(config);
     validateRetriesConfig(config);
+    validateFullyParallelConfig(config);
     validateUseConfig(config);
+    validateGroupUse(config);
+    validateWebServerConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/fully-parallel.d.ts

@@ -0,0 +1,3 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Checks the `fullyParallel` key of a config. Throws an Error that names the key */
+export declare function validateFullyParallelConfig(config: SamuraiTestConfig): void;

package/dist/config/fully-parallel.js

@@ -0,0 +1,6 @@
+/** Checks the `fullyParallel` key of a config. Throws an Error that names the key */
+export function validateFullyParallelConfig(config) {
+    if (config.fullyParallel !== undefined &&
+        typeof config.fullyParallel !== "boolean")
+        throw new Error(`fullyParallel must be true or false, got ${JSON.stringify(config.fullyParallel)}`);
+}

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

@@ -0,0 +1,8 @@
+import type { GroupUse, SamuraiGroup, SamuraiTestConfig } from "../types/config.js";
+/**
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`).
+ * Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export declare function validateGroupUse(config: SamuraiTestConfig): void;
+/** The `use` of the group called `name`; nothing when there is no such group or it has none */
+export declare function groupUseOf(groups: readonly SamuraiGroup[] | undefined, name: string): GroupUse;

package/dist/config/group-use.js

@@ -0,0 +1,41 @@
+import { USE_OPTION_NAMES, validateUseOptions } from "./use-options.js";
+const isSize = (value) => typeof value === "number" && Number.isInteger(value) && value > 0;
+/** Rewrites `use(): locale must ...` as `config.groups[1].use.locale: locale must ...` */
+function atGroup(place, err) {
+    if (!(err instanceof TypeError))
+        throw err;
+    const problem = err.message.replace(/^use\(\): /, "");
+    const name = /^(?:invalid |unknown )?(\w+)/.exec(problem)?.[1];
+    const known = name !== undefined &&
+        (name === "viewport" || USE_OPTION_NAMES.includes(name));
+    throw new TypeError(`${place}${known ? `.${name}` : ""}: ${problem}`);
+}
+/**
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`).
+ * Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export function validateGroupUse(config) {
+    config.groups?.forEach((group, index) => {
+        if (group.use === undefined)
+            return;
+        const place = `config.groups[${index}].use`;
+        try {
+            const raw = group.use;
+            const isObject = typeof raw === "object" && raw !== null && !Array.isArray(raw);
+            const { viewport, ...options } = (isObject ? raw : {});
+            // Anything but an object is refused here, with the message `test.use()` gives
+            validateUseOptions(isObject ? options : raw);
+            if (viewport !== undefined &&
+                viewport !== null &&
+                !(isSize(viewport.width) && isSize(viewport.height)))
+                throw new TypeError(`viewport must be { width, height } with whole numbers above 0, or null, got ${JSON.stringify(viewport)}`);
+        }
+        catch (err) {
+            atGroup(place, err);
+        }
+    });
+}
+/** The `use` of the group called `name`; nothing when there is no such group or it has none */
+export function groupUseOf(groups, name) {
+    return groups?.find((group) => group.name === name)?.use ?? {};
+}

package/dist/config/resolved-config.d.ts

@@ -45,6 +45,8 @@ export interface ResolvedConfig {
     workers?: number | string;
     /** The workers a run without `--workers` and `SAMURAI_WORKERS` uses on this machine */
     workersResolved: number;
+    /** The config's `fullyParallel` as written; absent when not set */
+    fullyParallel?: boolean;
     retries: number;
     forbidOnly: boolean;
     headless: boolean;

package/dist/config/resolved-config.js

@@ -62,6 +62,9 @@ export function resolveConfig(config, options) {
         bidiCommandTimeout: config.bidi?.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT,
         ...(config.workers !== undefined && { workers: config.workers }),
         workersResolved: resolveWorkers({ config: config.workers }),
+        ...(config.fullyParallel !== undefined && {
+            fullyParallel: config.fullyParallel,
+        }),
         // Matches the runner's `resolveRetries` without the command line flag and the environment (config/ cannot import runner/)
         retries: config.retries ?? DEFAULT_RETRIES,
         forbidOnly: forbidsOnly(config, env),

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,12 @@
-const NAMES = [
+/** 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 +15,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 +43,29 @@ 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))
             fail(`unknown option "${key}"`);
+    }
     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 +93,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 +180,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>;