@delacour/warden-e2e 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,60 @@
+import type { App } from "../app";
+import type { Device } from "../device";
+import type { Platform } from "../driver/driver.types";
+import type { E2eError } from "../errors";
+import type { Screen } from "../screen/screen";
+import type { Session } from "../session";
+import type { TraceWriter } from "./trace";
+export type { App, Device, Screen };
+/** What every test receives from the runner; `test.extend` adds to it. */
+export type TestFixtures = BaseFixtures;
+/** What every test receives; `test.extend` adds to it. */
+export type BaseFixtures = {
+    app: App;
+    device: Device;
+    screen: Screen;
+    platform: Platform;
+};
+export type LaunchMode = "fresh" | "none";
+/**
+ * `test.use({ systemAlerts })`: what to do when a read or wait sees an alert or sheet over the app (a permission
+ * prompt, "Open in …?", the Keychain "Save Password?" sheet, an app alert). `accept` / `dismiss` answer it with the
+ * buttons `device.alert("accept")` / `("dismiss")` press; `off` (the default) leaves it for the test.
+ */
+export type SystemAlerts = "accept" | "dismiss" | "off";
+export declare const SYSTEM_ALERTS: readonly SystemAlerts[];
+/** What a fixture factory gets for one attempt (or, for `beforeAll`/`afterAll`, the idle session). */
+export type FixtureContext = {
+    /**
+     * Inside an attempt, a view of the session bound to that attempt (`attemptSession`): its `signal`, `step`, `span`
+     * and `trace` stay that attempt's, so a fixture never acts in a later test.
+     */
+    session: Session;
+    /** aborts at the attempt deadline; every driver call and poll must honour it */
+    signal: AbortSignal;
+    launch: LaunchMode;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    /** absent = `off` */
+    systemAlerts?: SystemAlerts;
+};
+/**
+ * Builds `app`/`device`/`screen`. Registered on `session.fixtures` or via `setDefaultFixtureFactory`.
+ * The runner itself calls `app.open()` before the body when `launch` is `"fresh"`.
+ */
+export type FixtureFactory = (ctx: FixtureContext) => BaseFixtures | Promise<BaseFixtures>;
+/** The running attempt: where steps, screenshots and failure files go. Read it through the session. */
+export type AttemptContext = {
+    readonly signal: AbortSignal;
+    /** `<out>/<specId>/<title-slug>-<hash6>/` */
+    readonly dir: string;
+    /** spec name tagging step lines */
+    readonly short: string;
+    readonly trace: TraceWriter;
+    /** nesting depth of the step in progress (indents console lines) */
+    depth: number;
+    /** files written into `dir`, relative to it (reported in `TestResult.artifacts`) */
+    readonly files: Set<string>;
+    /** failures kept by `expect.soft`; the attempt fails with all of them once the body has settled */
+    readonly softFailures: E2eError[];
+};

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+export declare const testStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    passed: "passed";
+    skipped: "skipped";
+    "timed-out": "timed-out";
+}>;
+export declare const testResultSchema: z.ZodObject<{
+    file: z.ZodString;
+    title: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+        "timed-out": "timed-out";
+    }>;
+    durationMs: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    only: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    artifacts: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    device: z.ZodObject<{
+        udid: z.ZodString;
+        platform: z.ZodEnum<{
+            ios: "ios";
+            android: "android";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TestResult = z.infer<typeof testResultSchema>;
+export type TestStatus = z.infer<typeof testStatusSchema>;
+export type ResultsWriter = {
+    readonly path: string;
+    /** one JSON line; `appendFileSync` so a crash right after never loses an earlier line */
+    append(result: TestResult): void;
+};
+/** Append-only `results.jsonl` writer; the directory is created on first use. */
+export declare function openResults(path: string): ResultsWriter;
+/** Valid results in file order. Blank, truncated (killed mid-write) and invalid lines are skipped. */
+export declare function readResults(text: string): TestResult[];

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

@@ -0,0 +1,64 @@
+import type { BaseFixtures, LaunchMode, SystemAlerts } from "./fixtures.types";
+/** Headroom over the test timeout so warden's `AbortSignal` deadline fires before bun's own. */
+export declare const BUN_TIMEOUT_MARGIN_MS = 30000;
+export type UseOptions = {
+    timeout?: number;
+    actionTimeout?: number;
+    assertionTimeout?: number;
+    launch?: LaunchMode;
+    /**
+     * Answer an alert or sheet over the app whenever a read or wait sees one (it already has the snapshot, so a screen
+     * without one costs nothing): `dismiss` presses what `device.alert("dismiss")` would, `accept` what `("accept")`
+     * would, `off` (default) leaves it. It also answers the app's own alerts, so a test that taps those buttons
+     * itself keeps it `off`.
+     */
+    systemAlerts?: SystemAlerts;
+};
+export type ResolvedUse = {
+    timeoutMs: number;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    launch: LaunchMode;
+    systemAlerts: SystemAlerts;
+};
+/** Scope hooks are stored against the base fixtures; `test.extend(...).beforeEach` hooks are narrowed back to theirs by the runner (bun's own hooks take no arguments). */
+export type Hook = (fixtures: BaseFixtures) => void | Promise<void>;
+/** Marks `hook` as belonging to tests built from `fixtures` (entries compared by identity, in definition order). */
+export declare function ownHook(hook: Hook, fixtures: readonly object[]): Hook;
+export type Scope = {
+    /** describe titles from the root down to this scope */
+    readonly title: readonly string[];
+    readonly parent: Scope | undefined;
+    use: UseOptions;
+    readonly beforeEach: Hook[];
+    readonly afterEach: Hook[];
+    /** accepted for API parity: bun runs a file's tests serially unless `--concurrent` */
+    readonly serial: boolean;
+};
+/** The innermost `describe` being collected, else the root scope of the spec file making the call. */
+export declare function currentScope(): Scope;
+/**
+ * The scope of a `describe` call. Created when `describe()` is called — its parent is whatever is
+ * current then — because bun runs the callback later (nested ones after the parent's callback has
+ * returned), when the stack no longer says where it belongs.
+ */
+export declare function createScope(title: string, serial: boolean): Scope;
+/** Runs `body` (bun's `describe` callback) with `scope` current. */
+export declare function runInScope(scope: Scope, body: () => void): void;
+/** Root first, `scope` last. */
+export declare function scopeChain(scope: Scope): Scope[];
+/** `beforeEach`: outermost first. `afterEach`: innermost first. Hooks owned by another fixture set are left out. */
+export declare function hooksFor(scope: Scope, kind: "beforeEach" | "afterEach", fixtures?: readonly object[]): Hook[];
+/** Session defaults (env contract) under the nearest `test.use`, under the test's own `timeout`. */
+export declare function resolveUse(scope: Scope, defaults: Pick<ResolvedUse, "timeoutMs" | "actionTimeoutMs" | "assertionTimeoutMs">, testTimeout?: number): ResolvedUse;
+/** Timeouts known at collection time: the env when set, else the contract defaults. */
+export declare function registrationDefaults(env?: Readonly<Record<string, string | undefined>>): {
+    timeoutMs: number;
+    actionTimeoutMs: number;
+    assertionTimeoutMs: number;
+    platform: "ios" | "android" | undefined;
+};
+/** Records that a `.only` was collected (kept on `globalThis`: the preload and the specs may be separate bundles). */
+export declare function markOnly(): void;
+export declare function onlyWasSeen(): boolean;
+export declare function resetOnly(): void;

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,59 @@
+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;
+    /**
+     * Like the top-level `beforeEach`, typed with this `test`'s fixtures (the ones `extend` added too). It runs only
+     * for tests made with this `test` or one extended from it, not for the base `test`'s.
+     */
+    beforeEach(hook: (fixtures: F) => void | Promise<void>): void;
+    /** `beforeEach`'s counterpart: runs after each such test, even when it failed. */
+    afterEach(hook: (fixtures: F) => void | Promise<void>): 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, spec `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;