@delacour/warden-e2e 0.14.0 → 0.15.0

package/types/e2e/src/driver/settle.d.ts

@@ -1,4 +1,4 @@
-import type { Snapshot } from "./driver.types";
+import type { Element, Snapshot } from "./driver.types";
 export type SettleDeps = {
     quietMs: number;
     timeoutMs: number;
@@ -47,5 +47,7 @@ export declare function hashFallbackQuietMs(quietMs: number): number;
  * Side effects are injected so tests drive a fake clock.
  */
 export declare function settleByHash(poll: () => Promise<string>, deps: SettleDeps): Promise<SettleOutcome>;
+/** One element as `(role, identifier, label, value, frame to 1 pt)`: what `snapshotHash` hashes, per node. */
+export declare function elementKey(element: Element): string;
 /** Stable fingerprint over `(role, identifier, label, value, frame)` of every node in preorder. */
 export declare function snapshotHash(snapshot: Pick<Snapshot, "flat">): string;

package/types/e2e/src/expect/a11y-matchers.d.ts

@@ -28,6 +28,13 @@ export declare class DeviceAssertions {
     toPassA11yAudit(options?: PassA11yAuditOptions): Promise<void>;
     /** An announcement or live-region change whose text contains the string or matches the RegExp arrived (`.not`: none did within the timeout). */
     toHaveAnnounced(expected: TextMatch, options?: AnnouncedOptions): Promise<void>;
+    /**
+     * The on-screen keyboard is up (`.not`: it is gone), read from the accessibility tree. Polls until it holds or
+     * `timeout` (default: the assertion timeout) passes. Under `hardware` mode the keyboard never shows.
+     */
+    toHaveKeyboard(options?: {
+        timeout?: number;
+    }): Promise<void>;
     private failure;
     private run;
 }

package/types/e2e/src/index.d.ts

@@ -1,9 +1,10 @@
+export type { KeyboardMode } from "../../core/src/conditions/conditions.types";
 export type { A11yAuditOptions, A11yAuditResult, A11yEvent, A11yEventKind, A11yEventSource, A11yIgnore, A11yIssue, A11yRuleId, A11ySeverity, A11ySource, Announcement, ScreenReaderState, SpokenLine, } from "./a11y/a11y.types";
 export type { OpenOptions, OpenWaitUntil } from "./app";
 export type { CameraFacingChoice, CameraSetOptions, ClockInput, ConditionRun, DeviceCamera, DeviceClock, DeviceLocation, DeviceNetwork, DevicePermissions, Duration, FlapOptions, LocationPoint, NetworkSetOptions, NetworkStatus, RouteOptions, TimelineStepInput, } from "./conditions/device-conditions";
 export type { BiometricState, DeviceBiometrics } from "./device";
 export type { A11yAnnouncement, A11yAnnouncements, A11yAnnouncementsOptions, DeviceA11y, DeviceA11yAuditOptions, DeviceScreenReader, ScreenReaderSpokenOptions, } from "./device-a11y";
-export type { A11yOp, A11yState, CameraState } from "./driver/driver.types";
+export type { A11yOp, A11yState, CameraState, KeyboardResult, KeyboardState } from "./driver/driver.types";
 export { E2eError } from "./errors";
 export type { AnnouncedOptions, PassA11yAuditOptions } from "./expect/a11y-matchers";
 export { expect } from "./expect/expect";

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

@@ -39,6 +39,8 @@ export declare function isOnScreen(point: Point, screen: ScreenInfo): boolean;
  * field; Android keeps an input's text in `text`.
  */
 export declare function fieldValue(entry: NodeEntry): string;
+/** User-perceived characters in `text` (what a secure field shows one bullet for). */
+export declare function graphemes(text: string): number;
 /** What one read says a field holds: nothing, text, or (secure fields) a number of hidden characters. */
 export type FieldContent = {
     kind: "empty";
@@ -55,6 +57,11 @@ export type FieldContent = {
  * plain field showing its placeholder cannot be told from one holding that text and reads as `text`.
  */
 export declare function fieldContent(entry: NodeEntry): FieldContent;
+/**
+ * What a fill read-back of a secure field says it holds, given the typed `text`: `text` when it shows one bullet per
+ * character of it (the only check a masked field allows), else its bullets (never the typed text, in a message).
+ */
+export declare function maskedReading(entry: NodeEntry, text: string): string;
 /**
  * Backspaces that empty a field once the caret is at its end: one per character plus a spare. Secure fields are
  * counted by their dots. The fallback for a driver without select-all, and the retry when select-all did not empty

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

@@ -128,7 +128,9 @@ export declare class Runtime {
     excerpt(snapshot: Snapshot): string;
     /**
      * `poll` on this runtime's clock and abort signal; an abort throws instead of returning. `intervalMs` is a fixed gap
-     * between attempts instead of the back-off schedule.
+     * between attempts instead of the back-off schedule. The poll's deadline is the read deadline of every driver read
+     * made inside it (`withReadDeadline`), so a read that waits for the device (the cold iOS bridge) stops with it; a
+     * poll inside another keeps the nearer deadline.
      */
     poll<T, S>(step: (attempt: number) => Promise<PollStep<T, S>> | PollStep<T, S>, timeoutMs: number, options?: {
         intervalMs?: number;

package/types/e2e/src/screen/keyboard-cover.d.ts

@@ -0,0 +1,26 @@
+import type { Driver, DriverResult, Point, Rect, Snapshot } from "../driver/driver.types";
+import type { NodeEntry } from "./nodes";
+export type Cover = {
+    /** the keyboard's top edge */
+    top: number;
+    /** the free part of the nearest scroll container (its frame down to the keyboard), when the target sits in one */
+    scroller?: Rect;
+    /** points the content has to move up to clear the keyboard with a margin */
+    shift: number;
+};
+/** Whether `point` is under the keyboard of `snapshot`, and how to get clear of it; undefined when it is not. */
+export declare function coverOf(entry: NodeEntry, point: Point, snapshot: Snapshot): Cover | undefined;
+/**
+ * The finger path that moves the content of `scroller` up by about `shift` points (a shorter one when the free part
+ * is not that tall: the caller looks again and swipes again).
+ */
+export declare function scrollPath(scroller: Rect, shift: number): {
+    from: Point;
+    to: Point;
+};
+export declare const COVER_SCROLL_SWIPE: {
+    durationMs: number;
+    momentum: boolean;
+};
+/** Dismisses the keyboard the way `device.hideKeyboard()` does: iOS resigns the first responder (no Return), Android presses back. */
+export declare function dismissKeyboard(driver: Driver): DriverResult<void>;

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

@@ -134,7 +134,8 @@ export declare class Locator {
     degradedFailure(read: DegradedRead, waitedMs: number, snapshot: Observed["snapshot"] | undefined): E2eError;
     /**
      * One look that settles this locator. A whole read answers at once (never waits); a degraded one that cannot say
-     * whether the locator is there is looked at again until one can, within the action timeout, then `READ_DEGRADED`.
+     * whether the locator is there is looked at again until one can, within the action timeout (`quick`: within
+     * `QUICK_CHECK_WINDOW_MS`, for checks a spec branches on), then `READ_DEGRADED`.
      */
     private conclusive;
     /** The conclusive answer of `observed`, or undefined while it is `unknown`. */
@@ -219,6 +220,13 @@ export declare class Locator {
      * the kept snapshot sits outside the app, where the app-scoped hit-test may not see it, and the fresh look answers it.
      */
     private aimFromKept;
+    /**
+     * A target under the on-screen keyboard (the default `software` mode keeps it up) would get the touch on a key. In a
+     * scroll container it is scrolled into the free part of the screen (at most `MAX_COVER_SCROLLS` swipes, each looked at
+     * fresh); otherwise, or when scrolling does not clear it, the keyboard is dismissed once (`dismissKeyboard`). Either way
+     * the match is looked at again, and whatever that look shows is what the action uses: no retry.
+     */
+    private clearOfKeyboard;
     /**
      * Taps the one visible, enabled match. With `until` it is also the retrying tap: the press on a tab bar or a list row
      * right after a navigation is sometimes dropped with nothing on screen to tell, so it checks that `until` shows
@@ -226,9 +234,10 @@ export declare class Locator {
      */
     tap(options?: TapOptions): Promise<void>;
     /**
-     * One press; resolves to the snapshot it aimed from (the screen just before the press). A plain tap may aim from the
-     * kept snapshot (`aimFromKept`); a tap with `until` takes a fresh look, since the screen it aimed from is what the
-     * checks compare against to tell the press landed, and an older one could differ only because it was older.
+     * One press; resolves to the snapshot it aimed from (the screen just before the press) and the element pressed (none
+     * for a match only the React tree knows). A plain tap may aim from the kept snapshot (`aimFromKept`); a tap with
+     * `until` takes a fresh look, since the screen it aimed from is what the checks compare against to tell the press
+     * landed, and an older one could differ only because it was older.
      */
     private tapOnce;
     /**
@@ -236,9 +245,9 @@ export declare class Locator {
      * (`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
+     * the poll itself, which is also compared with the screen the press aimed from (`reacted`): once the screen reacted
+     * the press landed, so it is never sent again (`landed`, even when `until` is late); a screen that has not reacted
+     * on `UNCHANGED_CHECKS` checks in a row from `UNCHANGED_AFTER_MS` on is pressed again at once. A function
      * is called with the kept snapshot forgotten (after the first check), so its own reads take one new snapshot
      * between them rather than the previous check's; it gets the whole window.
      */

package/types/e2e/src/session.d.ts

@@ -37,6 +37,12 @@ export type Session = {
      * reopens the driver and devtools, once per session. Resolves `true` when the test is worth running again.
      */
     recoverHid: (() => Promise<boolean>) | undefined;
+    /**
+     * Present for iOS simulator runs: after a test failed, asks the open driver whether `warden-simd` restarted the
+     * sim's wedged accessibility service (backboardd, which quits the app) within the last `attemptMs` (waiting for a
+     * restart still in flight). Resolves `true` once per restart: the test is worth running again.
+     */
+    recoverAxWedge: ((attemptMs: number) => Promise<boolean>) | undefined;
     /** closes the open driver and devtools so the next call opens them afresh (the device was rebooted under them) */
     resetDevice(): Promise<void>;
     /** where the console reporter prints one line; default fd 1 */