@delacour/warden-e2e 0.0.0-stage → 0.1.1

package/types/e2e/src/runner/span.d.ts

@@ -0,0 +1,40 @@
+import { type SpanDetail } from "../driver/span-detail";
+import type { TraceEvent } from "./trace";
+/** Where spans go: the running attempt's `trace.jsonl` writer. */
+export type SpanSink = {
+    write(event: TraceEvent): void;
+};
+export type SpanOutcome = {
+    ok: boolean;
+    code?: string;
+};
+export type SpanOptions<T> = {
+    /** clock for `ts` and `ms`; default `Date.now` */
+    now?: () => number;
+    /** whether a call that did not throw still failed (a driver `Result`) */
+    verdict?: (value: T) => SpanOutcome;
+    /** scalars read off the result, merged over what the call noted with `noteSpanDetail` */
+    detail?: (value: T) => SpanDetail | undefined;
+};
+/** Times one call as a `span` (`device.*`, `read.*`); see {@link runSpan}. */
+export type SpanRunner = <T>(op: string, fn: () => Promise<T>, options?: SpanOptions<T>) => Promise<T>;
+/** The `code` of a thrown error (`E2eError`, a driver error), else `ERROR`. */
+export declare function codeOf(error: unknown): string;
+/**
+ * Writes one `span` event: `ts` is when the call started, `ms` how long it took. Tracing is diagnostic, so a sink
+ * that throws, or an `outcome` that does, never fails the call being timed.
+ */
+export declare function writeSpan(sink: SpanSink, span: {
+    op: string;
+    ts: number;
+    ms: number;
+    notes: SpanDetail;
+}, outcome: () => SpanOutcome & {
+    extra?: SpanDetail;
+}): void;
+/**
+ * Runs `fn` and writes one `span` event for it to `sink`: `ok`/`code` from the outcome, a throw recorded and
+ * rethrown unchanged. Without a sink (no attempt is running) it is just `fn()`. The sink is taken when the call
+ * starts, so a call that outlives its attempt still reports to that attempt's trace, never the next test's.
+ */
+export declare function runSpan<T>(sink: SpanSink | undefined, op: string, fn: () => Promise<T>, options?: SpanOptions<T>): Promise<T>;

package/types/e2e/src/runner/step.d.ts

@@ -0,0 +1,7 @@
+import type { AttemptContext } from "./fixtures.types";
+/**
+ * One reported step of the running attempt: writes `step-start` / `step-end` to `trace.jsonl` (and
+ * so to the console), nests by `depth`, and gives up as soon as the attempt deadline aborts, even
+ * if `fn` is a driver call that never answers. Without an attempt it just runs `fn`.
+ */
+export declare function runStep<T>(attempt: AttemptContext | undefined, kind: string, label: string, fn: () => Promise<T>, now?: () => number): Promise<T>;

package/types/e2e/src/runner/test.d.ts

@@ -0,0 +1,52 @@
+import type { Platform } from "../driver/driver.types";
+import { type BaseFixtures } from "./fixtures.types";
+import { type Hook, type UseOptions } from "./scope";
+export type TestOptions = {
+    /** ms for the whole attempt (hooks included); beats `test.use({ timeout })` */
+    timeout?: number;
+    skip?: boolean;
+    only?: boolean;
+    /** run only on these platforms (decided at collection time from `WARDEN_PLATFORM`) */
+    platforms?: readonly Platform[];
+    /** extra attempts after a failure; only the last attempt writes to `results.jsonl` */
+    retry?: number;
+};
+export type TestBody<F extends object> = (fixtures: F) => void | Promise<void>;
+export type TestCallable<F extends object> = {
+    (title: string, body: TestBody<F>): void;
+    (title: string, options: TestOptions, body: TestBody<F>): void;
+};
+/**
+ * `test.extend` fixtures: set up, call `use(value)`, clean up afterwards (runs even when the test
+ * failed). A fixture may read the ones defined before it in the same object (`base`).
+ */
+export type FixtureDefs<Base extends object, Extra extends object> = {
+    [K in keyof Extra]: (base: Base & Extra, use: (value: Extra[K]) => Promise<void>) => Promise<void>;
+};
+export type TestApi<F extends object> = TestCallable<F> & {
+    skip: TestCallable<F>;
+    only: TestCallable<F>;
+    /** a placeholder that never passes silently: it fails if bun is run with `--todo` */
+    todo(title: string): void;
+    skipIf(condition: boolean): TestCallable<F>;
+    /** applies to every test collected in the current scope (file or `describe`) */
+    use(options: UseOptions): void;
+    /** a `test` whose bodies also receive `Extra` */
+    extend<Extra extends object>(defs: FixtureDefs<F, Extra>): TestApi<F & Extra>;
+};
+/** The spec `test`. Fixtures: `{ app, device, screen, platform }`. */
+export declare const test: TestApi<BaseFixtures>;
+export type DescribeOptions = {
+    /** accepted for API parity: bun runs a file's tests one after another unless `--concurrent` */
+    serial?: boolean;
+};
+export declare function describe(title: string, body: () => void): void;
+export declare function describe(title: string, options: DescribeOptions, body: () => void): void;
+/** Runs before every test in this scope, outermost scope first; receives the test's `{ app, device, screen, platform }`. */
+export declare function beforeEach(hook: Hook): void;
+/** Runs after every test in this scope, innermost scope first, even when the test failed. */
+export declare function afterEach(hook: Hook): void;
+/** Once per file/`describe`, before its first test; receives the base fixtures (not the `extend` ones). */
+export declare function beforeAll(hook: Hook): void;
+/** Once per file/`describe`, after its last test. */
+export declare function afterAll(hook: Hook): void;

package/types/e2e/src/runner/trace.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import type { TestResult } from "./results";
+export declare const traceEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ts: z.ZodNumber;
+    kind: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"step-start">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+    }>;
+    ms: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    ts: z.ZodNumber;
+    kind: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"step-end">;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    ts: z.ZodNumber;
+    kind: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"screenshot">;
+}, z.core.$strip>, z.ZodObject<{
+    ts: z.ZodNumber;
+    kind: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"note">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"span">;
+    ts: z.ZodNumber;
+    op: z.ZodString;
+    ms: z.ZodNumber;
+    ok: z.ZodBoolean;
+    code: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>], "type">;
+/** One line of `trace.jsonl`; `ts` is epoch ms, `kind` the step family (`app`, `locator`, `expect`, …). */
+export type TraceEvent = z.infer<typeof traceEventSchema>;
+export type TraceWriter = {
+    readonly path: string;
+    /**
+     * Appends `event`. A `span` is only buffered (a test makes hundreds of driver calls and one `appendFileSync`
+     * each would show up in the timings it measures): the buffer is appended, in order, before the next other
+     * event, by {@link TraceWriter.flush}, or when it holds {@link SPAN_BUFFER_MAX} spans.
+     */
+    write(event: TraceEvent): void;
+    /** Appends the buffered spans; the runner calls it when an attempt ends. Spans written after it are lost. */
+    flush(): void;
+};
+/** Spans held in memory before they are appended without waiting for a step. */
+export declare const SPAN_BUFFER_MAX = 256;
+/** Append-only `trace.jsonl`; `mirror` also receives each event (the console reporter). */
+export declare function openTrace(path: string, mirror?: (event: TraceEvent) => void): TraceWriter;
+/** Valid events in file order; blank, truncated and invalid lines are skipped. */
+export declare function readTrace(text: string): TraceEvent[];
+type TestRef = Pick<TestResult, "file" | "title" | "device">;
+/** What the console reporter prints: a trace event, or a test boundary. */
+export type ConsoleEvent = TraceEvent | {
+    type: "test-start";
+    test: TestRef & {
+        startedAt: number;
+    };
+} | {
+    type: "test-end";
+    result: TestResult;
+};
+export type ConsoleLineOptions = {
+    /** prefix `[HH:MM:SS.mmm] `; false under `WARDEN_LOG_TIMESTAMPS=1` (warden stamps the log) */
+    clock: boolean;
+    /** step lines only: short spec name tagging the line (steps interleave across workers) */
+    short?: string;
+    /** step lines only: nesting depth, 0 = directly in the test */
+    depth?: number;
+};
+/** `ts` as local `HH:MM:SS.mmm` (the clock warden stamps its logs with). */
+export declare function clockOf(ts: number): string;
+/** `e2e/sign-in.e2e.ts` → `sign-in`. */
+export declare function shortName(file: string): string;
+/**
+ * The console line for an event, in PR #22's convention: `▶ test |<platform>| <file> › <title>` /
+ * `■ … <status> <N.NN>s on <device>` per test, `▸`/`▪` per step. `undefined` for events that print
+ * nothing (`screenshot`, `note`).
+ */
+export declare function formatConsoleLine(event: ConsoleEvent, opts: ConsoleLineOptions): string | undefined;
+export {};

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

@@ -0,0 +1,93 @@
+import type { Driver, Point, Rect, ScreenInfo } from "../driver/driver.types";
+import type { NodeEntry } from "./nodes";
+/** Pure helpers behind the locator actions: where to tap, how to swipe, how to empty a field. No driver calls. */
+/** The way the content scrolls: `down` reveals what is below, so the finger moves up. */
+export type SwipeDirection = "up" | "down" | "left" | "right";
+/** Fling strength of a swipe: `none` is a plain drag of half the surface. */
+export type Momentum = "none" | "slow" | "fast";
+export type SwipeVector = {
+    from: Point;
+    to: Point;
+    options: {
+        durationMs: number;
+        momentum: boolean;
+    };
+};
+/** Where a tap on `entry` lands: `position` is an offset from its top-left corner, else the driver's tap point or the centre. */
+export declare function tapPointOf(entry: NodeEntry, position?: Point): Point;
+/** A tap here focuses a text field with the caret after its text (right of where the text ends). */
+export declare function focusPoint(frame: Rect): Point;
+/** The finger path that scrolls `rect`'s content in `direction`, centred on the rect. */
+export declare function swipeVector(direction: SwipeDirection, rect: Rect, momentum?: Momentum): SwipeVector;
+/**
+ * The one swipe geometry: the finger path inside `rect`, centred, covering `fraction` (0-1) of it, that scrolls the
+ * content `direction` (`down` reveals what is below, so the finger travels up). Spec swipes, flow `swipe`/`scroll` steps
+ * and `warden ui scroll` use it as is; `warden ui gesture swipe <dir>` names the finger's direction instead and flips it
+ * (`fingerPath` in the CLI).
+ */
+export declare function contentPath(direction: SwipeDirection, rect: Rect, fraction: number): {
+    from: Point;
+    to: Point;
+};
+export declare function screenRect(screen: ScreenInfo): Rect;
+/** The part of `frame` that is on the screen (the whole frame when the screen size is unknown). */
+export declare function visibleRect(frame: Rect, screen: ScreenInfo): Rect;
+/** Whether a point is on the screen (an unknown screen size accepts everything). */
+export declare function isOnScreen(point: Point, screen: ScreenInfo): boolean;
+/**
+ * What a text field holds. Secure fields hold nothing readable; iOS reports the placeholder as the value of an empty
+ * field; Android keeps an input's text in `text`.
+ */
+export declare function fieldValue(entry: NodeEntry): string;
+/** What one read says a field holds: nothing, text, or (secure fields) a number of hidden characters. */
+export type FieldContent = {
+    kind: "empty";
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "dots";
+    count: number;
+};
+/**
+ * What `entry` holds, for deciding how to empty it. A placeholder the element names is `empty` (see `fieldValue`),
+ * and so is a secure field showing anything but dots. iOS reports `placeholder: null` for React Native inputs, so a
+ * plain field showing its placeholder cannot be told from one holding that text and reads as `text`.
+ */
+export declare function fieldContent(entry: NodeEntry): FieldContent;
+/**
+ * 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
+ * the field.
+ */
+export declare function clearKeyPresses(entry: NodeEntry): number;
+/** Default length of a locator or screen pinch. */
+export declare const PINCH_MS = 500;
+/** Default length of a locator or screen rotate. */
+export declare const ROTATE_MS = 500;
+/** Default length of a `screen.gesture.path`. */
+export declare const PATH_MS = 600;
+/** The scales a pinch accepts (exactly 1 is no gesture and is rejected separately). */
+export declare const SCALE_RANGE: readonly [0.1, 10];
+/** The most degrees a rotate accepts either way: two turns. */
+export declare const MAX_ROTATE_DEGREES = 720;
+/** The middle of `rect`. */
+export declare function centreOf(rect: Rect): Point;
+/**
+ * The finger distance from the centre a pinch starts at. Fingers end at `radius * scale`, so the larger of the two
+ * stays inside `REACH` of the rect's shorter half-side; the smaller never goes below 4% of the screen's shorter side.
+ * When both cannot hold (an extreme scale on a tiny rect) the gap wins, and the fingers may leave the rect.
+ */
+export declare function pinchRadius(rect: Rect, scale: number, screen: ScreenInfo): number;
+/** The finger distance a rotate uses: 30% of the rect's shorter side, kept between 4% and 30% of the screen's shorter side. */
+export declare function rotateRadius(rect: Rect, screen: ScreenInfo): number;
+/**
+ * Throws `INVALID_ARGUMENT` when the driver cannot do `cap`: `pinch` (pinch and rotate) needs `capabilities.pinch`,
+ * `path` needs `fingers` (default 1) or more of `capabilities.maxPointers`. Like `device.back()` on iOS, the error
+ * names the fix.
+ */
+export declare function requireGesture(driver: Driver, cap: "pinch" | "path", verb: string, fingers?: number): void;
+/** `INVALID_ARGUMENT` unless `scale` is a finite number in `SCALE_RANGE` other than 1. */
+export declare function assertScale(scale: number): void;
+/** `INVALID_ARGUMENT` unless `degrees` is finite, not 0 and within `MAX_ROTATE_DEGREES` either way. */
+export declare function assertDegrees(degrees: number): void;

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

@@ -0,0 +1,134 @@
+import type { DevtoolsFacet } from "../devtools/devtools.types";
+import type { Driver, DriverError, DriverResult, Snapshot } from "../driver/driver.types";
+import { E2eError } from "../errors";
+import type { SpanOptions, SpanRunner } from "../runner/span";
+import { type NodeIndex } from "./nodes";
+import { type Clock, type PollResult, type PollStep } from "./poll";
+import { type ReactMatch } from "./react-locator";
+import type { TextMatch } from "./text";
+/**
+ * What `screen` and `Locator` need from the test session. `Session` satisfies it as is; the optional members are
+ * filled in by the test wrapper when it exists (feature-detected, so queries work under a bare session too).
+ */
+export type ScreenHost = {
+    driver(): Promise<Driver>;
+    env: {
+        actionTimeoutMs: number;
+        assertionTimeoutMs?: number;
+    };
+    /** live override of the action timeout (`test.use({ actionTimeout })`) */
+    actionTimeout?: () => number;
+    /** live override of the assertion timeout (`test.use({ assertionTimeout })`) */
+    assertionTimeout?: () => number;
+    /** the running attempt's deadline: every poll stops when it aborts */
+    signal?: AbortSignal;
+    /** records one reported step around an action */
+    step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+    /** times a read (`read.isVisible`, …) as a trace-only `span`; absent = reads are not traced */
+    span?: SpanRunner;
+    /** polling time source; tests inject a fake */
+    clock?: Clock;
+    /**
+     * The running app's devtools, when there is one (a dev client with Metro). `getByTestId` falls back to the React
+     * component tree through it when the accessibility tree has no such node.
+     */
+    devtools?: () => Pick<DevtoolsFacet, "tree"> | undefined;
+    /**
+     * `test.use({ systemAlerts })`: answers the alert or sheet on top the way that option says (`device.alert("accept")`
+     * or `("dismiss")`) and resolves false when none could be answered. Reads and waits call it when the snapshot they
+     * already took shows one, so a screen without an alert costs nothing. Absent = alerts are left alone.
+     */
+    answerSystemAlert?: () => Promise<boolean>;
+};
+export type Observed = {
+    driver: Driver;
+    snapshot: Snapshot;
+    index: NodeIndex;
+};
+/** The look before this one, when the observation cache can tell (`ObserveOptions.withPrevious`). */
+export type Earlier = {
+    /** the kept snapshot from before this look, with no input between the two; undefined when there is none */
+    previous: Observed | undefined;
+    /** ms from the end of the last input to the start of this look; undefined before any input */
+    sinceInputMs: number | undefined;
+};
+export type Observation = {
+    ok: true;
+    observed: Observed;
+    earlier?: Earlier;
+} | {
+    ok: false;
+    error: DriverError;
+};
+/** What a look at the screen may do beyond reading it. */
+export type ObserveOptions = {
+    /**
+     * May answer with the snapshot the last read kept (`driver/observation-cache.ts`: nothing was pressed since and it is
+     * young). Only the first poll of a wait asks for it; a later one reads the device, or a wait could spin on a tree
+     * that stopped being true. Default: no.
+     */
+    reuse?: boolean;
+    /** Answer a system alert the snapshot shows when `test.use({ systemAlerts })` says to. Default: yes. */
+    alerts?: boolean;
+    /** Also say what the look before this one was (`Observation.earlier`), for an action's stability rule. Default: no. */
+    withPrevious?: boolean;
+};
+export declare class Runtime {
+    readonly host: ScreenHost;
+    private reactCache;
+    /** the index of each snapshot, so a snapshot that several reads share is indexed once */
+    private readonly indexed;
+    constructor(host: ScreenHost);
+    get clock(): Clock;
+    actionTimeout(): number;
+    assertionTimeout(): number;
+    /** A deadline `timeoutMs` (default: the action timeout) from now; `remaining()` is what is left of it. */
+    budget(timeoutMs?: number): {
+        remaining(): number;
+        total: number;
+    };
+    step<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    span<T>(op: string, fn: () => Promise<T>, options?: SpanOptions<T>): Promise<T>;
+    private indexOf;
+    /**
+     * One look at the device, indexed. A driver failure comes back as data so callers can retry the retryable. With
+     * `systemAlerts` on, an alert the screen shows is answered and the screen looked at again.
+     */
+    tryObserve(options?: ObserveOptions): Promise<Observation>;
+    /** What came before `look`, given the cache's answer from just before it was taken. */
+    private earlierThan;
+    /** Whether `snapshot` showed an alert that has now been answered. A screen without one costs no extra read. */
+    private answeredAlert;
+    /** Forgets the snapshot the last read kept: the next look reads the device. For a wait that makes its own reads between polls. */
+    forgetObservation(): Promise<void>;
+    /**
+     * Like `tryObserve`, but a driver failure is thrown. Retryable failures (a busy accessibility service, a stale
+     * helper) are retried within the action timeout first. The first look may reuse a kept snapshot (`reuse: false`
+     * opts out); the retries never do.
+     */
+    observe(options?: {
+        reuse?: boolean;
+    }): Promise<Observed>;
+    /**
+     * Components of the React tree whose testID matches, for `getByTestId` when the accessibility tree has none.
+     * Empty without devtools. Reads are throttled: inside the window the previous answer for the same query is reused.
+     */
+    reactMatches(testId: TextMatch, observed: Observed): Promise<ReactMatch[]>;
+    /**
+     * The interactive part of the tree as text, for failure messages. It indexes the snapshot again and renders up to
+     * `EXCERPT_LINES` lines, so call it only once an error is certain; keep the snapshot, not this text, while polling.
+     */
+    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.
+     */
+    poll<T, S>(step: (attempt: number) => Promise<PollStep<T, S>> | PollStep<T, S>, timeoutMs: number, options?: {
+        intervalMs?: number;
+    }): Promise<Exclude<PollResult<T, S>, {
+        status: "aborted";
+    }>>;
+    /** Unwraps a driver call made for an action; a failure becomes `ACTION_FAILED` naming the driver's code. */
+    drive<T>(verb: string, result: Awaited<DriverResult<T>>): T;
+}
+export declare function driverFailure(verb: string, error: DriverError, code?: "DRIVER" | "ACTION_FAILED"): E2eError;

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

@@ -0,0 +1,121 @@
+import type { Driver, DriverError, DriverResult, Point } from "../driver/driver.types";
+import { type Sleep } from "../driver/typing";
+import { type NodeEntry } from "./nodes";
+/**
+ * Reading back what a text field holds after typing, shared by the spec `fill` and `warden ui fill`.
+ *
+ * The accessibility value lags the keys by 100-200 ms (the app digests ~50 ms a character), and a controlled input
+ * can lose a key under load. So a read is never trusted on its own: the field must hold the wanted text on
+ * `CONFIRM_READS` consecutive reads `FIELD_POLL_MS` apart (a stale value from before the edit can equal the wanted
+ * text once), and the wait extends while the value is still changing.
+ */
+export declare const FIELD_POLL_MS = 50;
+/** While the value keeps changing, wait at least this long for its next change. */
+export declare const FIELD_PROGRESS_MS = 1000;
+/** Consecutive reads that must equal the wanted text. */
+export declare const CONFIRM_READS = 2;
+/** When the field already held the wanted text before the edit, a stale read can match: trust only a longer run. */
+export declare const STALE_RISK_READS = 4;
+/**
+ * Consecutive matching reads to trust for `text` typed into `entry` (the field as seen before the edit): the longer
+ * `STALE_RISK_READS` only when it already held that text. A placeholder shown as the value (one the element names, or a
+ * secure field's) is not text it held.
+ */
+export declare function confirmReadsFor(entry: NodeEntry | undefined, text: string): number;
+export type FieldReading = {
+    kind: "value";
+    value: string;
+}
+/** the field could not be read this time (gone, ambiguous, driver busy); `note` is what a failure message shows */
+ | {
+    kind: "unreadable";
+    note: string;
+};
+export type FieldOutcome<E> = {
+    status: "confirmed";
+} | {
+    status: "mismatch";
+    held: string;
+} | {
+    status: "failed";
+    error: E;
+};
+export type ConfirmRequest<E> = {
+    /** one look at the field; `{ ok: false }` ends the wait at once */
+    read: () => Promise<{
+        ok: true;
+        reading: FieldReading;
+    } | {
+        ok: false;
+        error: E;
+    }>;
+    text: string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    /** how long to keep looking when nothing changes */
+    budgetMs: number;
+    /** consecutive matching reads to trust; default `CONFIRM_READS` */
+    reads?: number;
+    /** hard cap including the extension for progress */
+    maxMs?: number;
+};
+/** Polls the field until it holds `text` on consecutive reads, or the budget (extended while it changes) runs out. */
+export declare function confirmFieldValue<E>(request: ConfirmRequest<E>): Promise<FieldOutcome<E>>;
+/** What the field behind `wanted` shows right now by a hit-test at its centre (about 10 ms, unlike a full snapshot), or undefined when that cannot tell. */
+export declare function hitTestField(driver: Driver, wanted: NodeEntry): Promise<{
+    ok: true;
+    entry: NodeEntry | undefined;
+} | {
+    ok: false;
+    error: DriverError;
+}>;
+/** Gap between the hit-tests that wait for a tapped field to take focus. */
+export declare const FOCUS_POLL_MS = 20;
+/**
+ * Most hit-tests (~10 ms each, `FOCUS_POLL_MS` apart) spent waiting for a tapped field to report focus: about 0.75 s.
+ * Measured on a simulator: focus shows 70-250 ms after the tap, the keyboard coming up included.
+ */
+export declare const FOCUS_POLLS = 25;
+/**
+ * Taps `point` to focus the text field `entry` and, on iOS, returns once the field reports focus (a hit-test at
+ * `point`, every `FOCUS_POLL_MS`, at most `FOCUS_POLLS` times). Keys sent while focus is still moving reach a React
+ * Native controlled input during its focus re-render and are lost or reordered ("Hllo", "lol, World 123!H"): 5 in 400
+ * tap-then-type runs, none in 300 that waited for focus (85-112 ms) or in 200 that re-tapped the field already focused. So a field
+ * that already had focus, Android (`warden-uiad` types into the focused node itself), a bare coordinate and a
+ * hit-test that cannot tell (failed, or another element there, e.g. content that moved up for the keyboard) are not
+ * waited on.
+ */
+export declare function tapToFocus(driver: Driver, sleep: Sleep, point: Point, entry: NodeEntry | undefined): DriverResult<void>;
+/**
+ * How a field is emptied. `auto` selects everything and presses one Backspace when the driver can select all, else
+ * presses one Backspace per character; `counted` always presses one per character (the retry after select-all left
+ * text behind, e.g. a field that refuses Cmd+A). `setText` is `auto`, except that `focusClearType` replaces a plain
+ * filled field in one `setText` call where the driver has it (Android `warden-uiad`): opt-in, see `SETTEXT_ENV`.
+ */
+export type ClearMethod = "auto" | "counted" | "setText";
+/**
+ * `WARDEN_ANDROID_SETTEXT=1` makes `auto` behave as `setText` in `focusClearType`. Off by default: the server's
+ * `setText` writes to the node its accessibility cache says has focus, which can still be the field filled before
+ * (it does not re-read focus the way typing and select-all do), so a quick fill of a second field could overwrite the first.
+ */
+export declare const SETTEXT_ENV = "WARDEN_ANDROID_SETTEXT";
+/** Whether `env` opts `auto` fills into `setText` (`SETTEXT_ENV`). */
+export declare function setTextOptedIn(env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * Taps `point` and empties what `entry` shows: select-all and one Backspace when the driver offers it, else one
+ * Backspace per character (see `focusAndSelect`). The clear routine behind the spec `clear` and `warden ui clear`.
+ */
+export declare function focusAndClear(driver: Driver, sleep: Sleep, point: Point, entry: NodeEntry | undefined, method?: ClearMethod): DriverResult<void>;
+/**
+ * Empties the field as `focusAndClear` does, then types `text` (nothing for the empty string). A selected text is not
+ * deleted first: the first typed character replaces the whole selection, which saves a Backspace. If the select-all
+ * did not take, the old text stays and the typed text lands after it; the confirm read sees that and the retry uses the
+ * counted method.
+ *
+ * With the `setText` method (or `auto` under `WARDEN_ANDROID_SETTEXT=1`, read from `env`), on a driver with `setText`
+ * (Android `warden-uiad`) a plain field that holds text is replaced in one call after the focus tap, instead of
+ * select-all then typing; the read-back after a `fill` checks it took, and the counted retry types. An empty field gains
+ * nothing from it, and a secure one cannot be read back, so both are typed as before. A `setText` that fails falls back
+ * to select-all and typing, without a second tap.
+ */
+export declare function focusClearType(driver: Driver, sleep: Sleep, point: Point, entry: NodeEntry | undefined, text: string, method?: ClearMethod, env?: Readonly<Record<string, string | undefined>>): DriverResult<void>;