@delacour/warden-e2e 0.2.0 → 0.4.0

package/types/e2e/src/screen/locator.d.ts

@@ -1,6 +1,7 @@
 import type { KeyName, Modifier, Point, Rect } from "../driver/driver.types";
 import { type Momentum, type SwipeDirection } from "./actions";
 import type { Observed, Runtime } from "./context";
+import { type FillVia } from "./field";
 import type { NodeEntry } from "./nodes";
 import { type RoleOptions, type TestIdOptions, type TextQueryOptions } from "./queries";
 import { type LocatorExpression } from "./query";
@@ -39,6 +40,10 @@ export type TapOptions = ActionOptions & {
     /** gap between checks of `until`. Default 250 ms. Needs `until`. */
     pollMs?: number;
 };
+/** `fill` puts the text in by paste where the driver can (iOS) or types it: see `FillVia`. A retry always types. */
+export type FillOptions = ActionOptions & {
+    via?: FillVia;
+};
 export type LongPressOptions = ActionOptions & {
     durationMs?: number;
 };
@@ -137,12 +142,21 @@ export declare class Locator {
      * driver with a cheap hit-test first tries `aimFromKept`, which checks the kept snapshot with a hit-test instead.)
      * A fresh snapshot can also be of a screen still moving, so a match is taken only once its frame held still across
      * two looks with no input between them (Playwright's "stable"): the look a read or an `expect` kept, when there is
-     * one, costs nothing; with none, a look less than `STABLE_INPUT_GAP_MS` after an input is checked by one more. An
-     * element that never stops moving is taken after `MAX_STABILITY_LOOKS` extra looks.
+     * one, costs nothing; with none, a look less than `STABLE_INPUT_GAP_MS` after an input is checked by one more: a
+     * hit-test at the element where that is cheap (`stillByHitTest`), else a snapshot. An element that never stops
+     * moving is taken after `MAX_STABILITY_LOOKS` extra looks.
      */
     private actionable;
     /** One look of `actionable`: done, not yet, or `moving` (the match has not held still yet; look again at once). */
     private actionableLook;
+    /**
+     * The second look of the stable-frame rule as a hit-test, where that is cheap (`capabilities.cheapHitTest`, iOS:
+     * one element back instead of the whole tree): the element held still when the hit at its tap point is that element
+     * (`sameElement`, as in `aimFromKept`). Only for a look with nothing to compare against (the one that followed an
+     * input): a look that differs from the one before it is known to be moving. Never with system alerts answered: the
+     * app-scoped hit-test may not see an alert that came up since the look, the full second look does.
+     */
+    private stillByHitTest;
     /**
      * Whether `entry`'s frame, to 1 pt, is where the look before this one had this locator's one match. Without that look:
      * still unless an input ended less than `STABLE_INPUT_GAP_MS` before this one. No observation cache = still (no history).
@@ -173,7 +187,10 @@ export declare class Locator {
      */
     private tapOnce;
     /**
-     * Polls `plan.until` for `plan.windowMs`, one look at the screen per check. A locator is checked on the snapshot of
+     * Polls `plan.until` for `plan.windowMs`, one look at the screen per check, the first one right after the press
+     * (`driver.tap` returns once the HID press is over, ~85 ms, and an AX read queues behind the app's main thread, so
+     * that look usually already shows the screen the press made; measured: holding it back to `pollMs` saved no read
+     * and cost 250 ms a press). A locator is checked on the snapshot of
      * the poll itself, which is also compared with `pressedOn` (the hash of the screen the press aimed from): once the
      * screen changed the press landed, so it is never sent again (`landed`, even when `until` is late); a screen still
      * unchanged on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
@@ -188,10 +205,12 @@ export declare class Locator {
      * Replaces the content of a text field: focus with the caret at the end, empty it (select all and type over the selection when
      * the driver can, nothing for a field that is empty or shows a placeholder), type, then poll until the field holds
      * the text on consecutive reads (the accessibility value lags the keys). A mismatch is retried once with one Backspace
-     * per character and a retype (a field that refuses select-all). Secure fields cannot be read back, so they are not
+     * per character and a retype (a field that refuses select-all). `via` (default `"paste"`) is how the text goes in on
+     * the first attempt: a paste on iOS, typing where the driver cannot paste or when the pasteboard write fails; the
+     * retry always types, so a field that mangles a paste (a mask, a maxLength) still ends up right. Secure fields cannot be read back, so they are not
      * verified.
      */
-    fill(text: string, options?: ActionOptions): Promise<void>;
+    fill(text: string, options?: FillOptions): Promise<void>;
     /** Empties a text field (select all and one Backspace when the driver can), then checks it is empty (one more pass of counted Backspaces when it is not). */
     clear(options?: ActionOptions): Promise<void>;
     /** Types at the caret; the field is tapped (caret to the end) first unless it already has focus. */