@delacour/warden-e2e 0.6.0 → 0.8.0

package/types/e2e/src/conditions/device-conditions.d.ts

@@ -0,0 +1,198 @@
+import { type NetworkInput } from "../../../core/src/conditions/conditions.config";
+import type { CameraFacing, ClockCondition, HostFault, LatLon, LocationCondition, LocationScenario, NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yOp, A11yState, BatteryOp, BatteryState, CameraState, Driver, LocaleState, NetworkState, PermissionGrants, PermissionsState, PushPayload, SettingOptions, TimezoneState } from "../driver/driver.types";
+import type { E2eEnv } from "../env";
+import { type ConditionSink } from "./condition-events";
+import type { ConditionRecorder } from "./lease-recorder";
+import { type TickerClock } from "./route-ticker";
+import { type SchedulerOutcome, type SchedulerStatus } from "./scheduler";
+/** A duration in ms, or text like `"10s"`, `"2m"`, `"2d"`. */
+export type Duration = string | number;
+export type NetworkSetOptions = {
+    /** iOS: relaunch the app when it runs without the warden network dylib (the default is to fail and say so) */
+    relaunch?: boolean;
+};
+export type FlapOptions = {
+    /** how long the network stays up per cycle */
+    up: Duration;
+    /** how long it stays down (offline) per cycle */
+    down: Duration;
+    /** each phase lasts its length +/- this percent, drawn from `seed` */
+    jitterPct?: number;
+    /** same seed, same sequence; default 1 */
+    seed?: number;
+    /** the "up" condition and what `stop()` puts back; default `"online"` */
+    base?: NetworkInput;
+};
+/** A running flap or timeline. It is stopped by `stop()` and, at the latest, when the test ends. */
+export type ConditionRun = {
+    /** stops it (a flap puts its base back first) and resolves with how it ended */
+    stop(): Promise<SchedulerOutcome>;
+    /** resolves when it ended; never rejects */
+    readonly done: Promise<SchedulerOutcome>;
+    status(): SchedulerStatus;
+};
+export type NetworkStatus = {
+    /** what is in effect (`flap` while one runs) */
+    condition: NetworkCondition;
+    faults: readonly HostFault[];
+    flapping: boolean;
+};
+export type DeviceNetwork = {
+    /**
+     * Puts the network into `condition`: `"online"`, `"offline"`, a preset (`"edge"`, `"3g"`, `"4g"`, `"lte"`,
+     * `"wifi"`, `"slow"`, `"lossy"`) or a full `NetworkCondition`. A running flap stops first. On iOS the app must
+     * run with the warden network dylib: a suite that declares `conditions.network` launches it that way, else the
+     * call fails until you pass `{ relaunch: true }`.
+     */
+    set(condition: NetworkInput, options?: NetworkSetOptions): Promise<NetworkState>;
+    /** Runs `fn` under `condition` and puts the previous condition (and flap) back after, also when `fn` throws. */
+    during<T>(condition: NetworkInput, fn: () => Promise<T> | T, options?: NetworkSetOptions): Promise<T>;
+    /** Alternates up and down until `stop()` or the end of the test; resolves once the first phase is in place. */
+    flap(options: FlapOptions): Promise<ConditionRun>;
+    /** Replaces the per-host faults (status, reset, delay, blackhole by host glob); `[]` clears. */
+    fault(rules: HostFault | readonly HostFault[]): Promise<{
+        notes: readonly string[];
+    }>;
+    status(): Promise<NetworkStatus>;
+    /** Stops a flap, clears the faults and returns to the suite's `conditions.network` (online when it has none). */
+    reset(): Promise<void>;
+};
+export type LocationPoint = {
+    lat: number;
+    lon: number;
+    altM?: number;
+};
+export type RouteOptions = {
+    speedMps?: number;
+    intervalS?: number;
+    loop?: boolean;
+};
+export type DeviceLocation = {
+    set(point: LocationPoint): Promise<void>;
+    /** Plays waypoints (or a `{ gpx }` file, relative to the working directory) at `speedMps`. */
+    route(points: readonly LatLon[] | {
+        gpx: string;
+    }, options?: RouteOptions): Promise<void>;
+    scenario(name: LocationScenario): Promise<void>;
+    clear(): Promise<void>;
+};
+/** An ISO string, a `Date` or epoch milliseconds. */
+export type ClockInput = string | number | Date;
+export type DeviceClock = {
+    /** Sets the device's wall clock; it runs on from there unless `frozen`. */
+    set(at: ClockInput, options?: {
+        frozen?: boolean;
+    }): Promise<void>;
+    /** Moves the clock on by `by` (`"2d"`, or ms). */
+    advance(by: Duration): Promise<void>;
+    /** Runs `fn` with the clock at `at`, then puts the previous clock back, also when `fn` throws. */
+    during<T>(at: ClockInput, fn: () => Promise<T> | T, options?: {
+        frozen?: boolean;
+    }): Promise<T>;
+    /** Back to the suite's `conditions.clock`, else real time. */
+    reset(): Promise<void>;
+    status(): ClockCondition;
+};
+export type DevicePermissions = {
+    /**
+     * Sets permissions of the app, per name (`location`, `camera`, `photos`, `contacts`, `notifications`, `microphone`,
+     * ...): `"granted"`, `"denied"` or `"unset"` (asks again). The result lists the names this platform skipped. Set
+     * them before `app.open()`: iOS terminates a running app when its permission changes.
+     */
+    set(grants: PermissionGrants, options?: SettingOptions): Promise<PermissionsState>;
+    /** Puts every permission this test set back to the suite's `conditions.permissions`, else `"unset"`. */
+    reset(options?: SettingOptions): Promise<void>;
+};
+export type TimelineStepInput = {
+    /** when, from the start of the timeline */
+    at: Duration;
+    network?: NetworkInput;
+    location?: LocationCondition | LatLon;
+};
+/** What the runner needs of a device's conditions; reached through {@link conditionsOf}, not on `Device`. */
+export type ConditionsInternals = {
+    /** the suite declares a network or clock condition, or one is active: iOS must launch with the dylib */
+    wantsInject(): boolean;
+    /** puts the suite's declared network, location and clock in place; warns once about areas not applied yet */
+    applyBaseline(): Promise<void>;
+    /** something changed or still runs: `teardown` has work to do */
+    dirty(): boolean;
+    /** stops flaps and timelines, and puts every area this device changed back to the baseline */
+    teardown(): Promise<void>;
+    /** the suite declares something to apply */
+    readonly declared: boolean;
+};
+/** `facing` of `device.camera.set` / `clear`: one camera, or `"both"`. */
+export type CameraFacingChoice = CameraFacing | "both";
+export type CameraSetOptions = {
+    /** which camera plays the asset; default `"back"` */
+    facing?: CameraFacingChoice;
+    /** video only: play again from the start at the end; default true */
+    loop?: boolean;
+};
+export type DeviceCamera = {
+    /**
+     * Feeds the png, jpg, heic, mp4 or mov at `path` (relative to the spec file) into the app's camera, replacing what
+     * that facing played; the other facing keeps its feed. The result says when it shows: `appliesOnLaunch` (iOS: an
+     * app launched without the camera sees it from the next launch), `appliesOnCameraOpen` (Android: the app's next
+     * camera open) or `rebooted` (Android: a video feed restarted the emulator). Android needs a `--camera` device
+     * (`E_CAMERA_DEVICE` otherwise); a missing or unsupported file fails with `E_CAMERA_NOT_FOUND` / `E_CAMERA_MEDIA`.
+     * Taken off when the test ends (back to the suite's `camera`).
+     */
+    set(path: string, options?: CameraSetOptions): Promise<CameraState>;
+    /** Takes the feed off one camera, or both (the default). */
+    clear(facing?: CameraFacingChoice): Promise<CameraState>;
+    /** The feeds this spec has in place. */
+    status(): Promise<CameraState>;
+};
+export type DeviceConditions = {
+    camera: DeviceCamera;
+    network: DeviceNetwork;
+    location: DeviceLocation;
+    clock: DeviceClock;
+    permissions: DevicePermissions;
+    /** Device timezone (`"Asia/Tokyo"`); `null` puts it back. iOS: applies to the app launched next. */
+    timezone(tz: string | null): Promise<TimezoneState>;
+    /** The app's locale (`"fr-FR"`); `null` puts it back. iOS: applies to the app launched next. Android 13+. */
+    locale(tag: string | null, options?: SettingOptions): Promise<LocaleState>;
+    /** Text size (a name like `"accessibility-large"` or a scale like `1.5`), bold text, contrast, reduce motion; `null` resets. */
+    a11y(op: A11yOp | null): Promise<A11yState>;
+    /** Battery level and charging. Android emulators: real. iOS: the status bar only (`cosmetic: true`). `null` resets. */
+    battery(op: BatteryOp | null): Promise<BatteryState>;
+    /** Android: a critical trim-memory signal to the running app. iOS: `E_UNSUPPORTED` (no delivery mechanism works). */
+    memoryWarning(options?: SettingOptions): Promise<void>;
+    /** iOS: delivers an APNs payload (`{ aps: { alert: ... } }`) to the app. Android: `E_UNSUPPORTED`. */
+    push(payload: PushPayload, options?: SettingOptions): Promise<void>;
+    timeline(steps: readonly TimelineStepInput[]): Promise<ConditionRun>;
+    internals: ConditionsInternals;
+};
+export type DeviceConditionsDeps = {
+    driver: Driver;
+    env: E2eEnv;
+    /** the running attempt's signal, read per call */
+    signal: () => AbortSignal | undefined;
+    /** where condition events go (`results.jsonl`); default none */
+    sink?: ConditionSink;
+    /** time for flaps, timelines and event stamps */
+    tickerClock?: TickerClock;
+    /** notes (a restore that failed, areas not applied yet); default stderr */
+    log?: (line: string) => void;
+    /** where changes are written on the device's lease so release can undo them after a crash; default none */
+    recorder?: ConditionRecorder;
+    /** the warden home camera assets are staged under; default `$WARDEN_HOME` / `~/.warden` */
+    wardenHome?: string;
+    /** the directory a relative camera path is resolved against; default the calling spec file's, else `specsDir`, else cwd */
+    specDir?: () => string | undefined;
+};
+/** Ties a device (or a wrapper of it) to its conditions' runner hooks; `Device` itself does not expose them. */
+export declare function registerConditions(device: object, internals: ConditionsInternals): void;
+/** The runner hooks of a device made by `createDevice` (or a `traceDevice` wrapper of one). */
+export declare function conditionsOf(device: object): ConditionsInternals | undefined;
+/** The condition sink for a session: events append to its `results.jsonl`; none without one. */
+export declare function conditionSinkFor(session: {
+    results?: {
+        path: string;
+    };
+}): ConditionSink | undefined;
+export declare function createDeviceConditions(deps: DeviceConditionsDeps): DeviceConditions;

package/types/e2e/src/conditions/geo.d.ts

@@ -0,0 +1,15 @@
+import type { LatLon } from "../../../core/src/conditions/conditions.types";
+/** Great-circle distance in metres. */
+export declare function haversineM(a: LatLon, b: LatLon): number;
+/** Initial bearing from `a` to `b`, degrees clockwise from north in [0, 360). */
+export declare function bearingDeg(a: LatLon, b: LatLon): number;
+/** The point a fraction `f` (0..1) of the way along the great circle from `a` to `b`. */
+export declare function interpolate(a: LatLon, b: LatLon, f: number): LatLon;
+export declare function pathLengthM(points: readonly LatLon[]): number;
+/**
+ * One fix per interval along `points`: a fix every `speedMps * intervalS` metres of path, the first
+ * waypoint first and the last waypoint last (no duplicate when the length is an exact multiple).
+ */
+export declare function routeSteps(points: readonly LatLon[], speedMps: number, intervalS: number): LatLon[];
+/** 7 decimals (about 1 cm), no trailing zeros, never an exponent. */
+export declare function formatCoord(n: number): string;

package/types/e2e/src/conditions/gpx.d.ts

@@ -0,0 +1,8 @@
+import type { LatLon } from "../../../core/src/conditions/conditions.types";
+import { type Result } from "../../../types/src/result";
+/**
+ * Tolerant, dependency-free GPX reader: every `<trkpt>`, `<rtept>` and `<wpt>` with a valid `lat` and
+ * `lon` attribute, in document order. Comments are dropped, a point with a bad or missing coordinate is
+ * skipped, and truncated XML yields the points before the break. No points at all is an error.
+ */
+export declare function parseGpx(xml: string): Result<LatLon[]>;

package/types/e2e/src/conditions/lease-recorder.d.ts

@@ -0,0 +1,27 @@
+import type { ConditionArea, ConditionValues } from "../../../core/src/conditions/conditions.types";
+import { type PidAlive } from "../../../core/src/liveness";
+import type { E2eEnv } from "../env";
+import { type StoreOpener } from "./lease-store";
+/**
+ * Writes what a spec changed on its device to the lease (`lease_conditions`), so `warden release` / gc can undo it
+ * when the spec process dies before its own teardown. Best effort: a failure is logged and never reaches the test.
+ */
+export type ConditionRecorder = {
+    /** the device now has `value` in `area` */
+    record<A extends ConditionArea>(area: A, value: ConditionValues[A]): void;
+    /**
+     * the device is back at its baseline `value`: when that is `neutral` (nothing to undo) the area is forgotten,
+     * unless a process is still held for it (a live shaping proxy), which release must still stop
+     */
+    settle<A extends ConditionArea>(area: A, value: ConditionValues[A], neutral: boolean): void;
+};
+export type LeaseRecorderOptions = {
+    leaseId: string;
+    openStore?: StoreOpener;
+    now?: () => number;
+    log?: (line: string) => void;
+    pidAlive?: PidAlive;
+};
+export declare function createLeaseRecorder(o: LeaseRecorderOptions): ConditionRecorder;
+/** The recorder for a spec under a lease; none without `WARDEN_LEASE_ID` (a bare `bun test` has no lease to record on). */
+export declare function leaseRecorderFor(env: Pick<E2eEnv, "leaseId">): ConditionRecorder | undefined;

package/types/e2e/src/conditions/lease-store.d.ts

@@ -0,0 +1,9 @@
+import { type Store } from "../../../core/src/store";
+import { type Result } from "../../../types/src/result";
+/** Opens the lease store; a failure is a `Result`, never a throw. */
+export type StoreOpener = () => Result<Store>;
+/**
+ * The spec process's one connection to the lease store, opened on first use: a run that sets no condition and
+ * shapes no network never opens it. Connections are kept per db path for the life of the process.
+ */
+export declare function sharedStoreOpener(env?: Readonly<Record<string, string | undefined>>): StoreOpener;

package/types/e2e/src/conditions/location-plan.d.ts

@@ -0,0 +1,17 @@
+import type { LatLon, LocationCondition } from "../../../core/src/conditions/conditions.types";
+import { type Result } from "../../../types/src/result";
+export type ReadText = (path: string) => Promise<string>;
+export type RoutePlan = {
+    points: readonly LatLon[];
+    speedMps: number;
+    intervalS: number;
+    loop: boolean;
+};
+export declare function loadGpxPoints(path: string, readText: ReadText): Promise<Result<LatLon[]>>;
+/**
+ * Everything a ticker needs for the moving location ops (`route`, `gpx`, `scenario`): waypoints, pace,
+ * loop. Used where the platform has no player of its own (Android); iOS hands the waypoints to simctl.
+ */
+export declare function planRoute(op: Extract<LocationCondition, {
+    kind: "route" | "gpx" | "scenario";
+}>, readText: ReadText): Promise<Result<RoutePlan>>;

package/types/e2e/src/conditions/location-scenarios.data.d.ts

@@ -0,0 +1,17 @@
+import type { LatLon, LocationScenario } from "../../../core/src/conditions/conditions.types";
+/**
+ * Apple's names for the three simulated-location scenarios `simctl location <udid> run` knows (verify
+ * with `xcrun simctl location <udid> list`).
+ */
+export declare const IOS_SCENARIO_NAMES: Record<LocationScenario, string>;
+export type ScenarioRoute = {
+    points: readonly LatLon[];
+    speedMps: number;
+    loop: boolean;
+};
+/**
+ * Android parity: a similar path and pace for each scenario, played by the route ticker. These are
+ * warden's own waypoints around Apple Park, Cupertino, not Apple's data: same character (walking
+ * pace loop, cycling loop, highway stretch), not identical coordinates.
+ */
+export declare const ANDROID_SCENARIOS: Record<LocationScenario, ScenarioRoute>;

package/types/e2e/src/conditions/route-ticker.d.ts

@@ -0,0 +1,53 @@
+import type { LatLon } from "../../../core/src/conditions/conditions.types";
+import { type Result } from "../../../types/src/result";
+/** simctl's own default pace, so a route moves the same on both platforms. */
+export declare const DEFAULT_SPEED_MPS = 20;
+export declare const DEFAULT_INTERVAL_S = 1;
+export type TickerClock = {
+    now(): number;
+    /** resolves after `ms`, or as soon as `signal` aborts */
+    sleep(ms: number, signal: AbortSignal): Promise<void>;
+};
+export declare const realTickerClock: TickerClock;
+export type TickerRoute = {
+    points: readonly LatLon[];
+    speedMps?: number;
+    intervalS?: number;
+    loop?: boolean;
+};
+export type TickerDeps = TickerClock & {
+    /** send one fix; return an error string (or throw) to count a failure, nothing when it landed */
+    fix(point: LatLon): Promise<string | undefined>;
+};
+export type TickerOutcome = {
+    ticks: number;
+    stopped: "finished" | "aborted";
+} | {
+    ticks: number;
+    stopped: "failed";
+    error: string;
+};
+export type RouteTicker = {
+    /** idempotent; the loop exits before sending another fix */
+    stop(): void;
+    done: Promise<TickerOutcome>;
+};
+/**
+ * Plays `route` as one fix per `intervalS`, paced against the clock (a slow fix shortens the next
+ * sleep). Runs in this process: specs hold the handle and `stop()` it, a detached child runs the same
+ * loop from `route-ticker.main.ts`. Ends when the route is done (never, with `loop`), when stopped, or
+ * after {@link MAX_CONSECUTIVE_FAILURES} failed fixes in a row.
+ */
+export declare function startRouteTicker(route: TickerRoute, deps: TickerDeps): RouteTicker;
+/** What the detached child needs: the adb to call and the route to play. */
+export type TickerConfig = TickerRoute & {
+    adb: string;
+    serial: string;
+};
+export declare function parseTickerConfig(raw: string): Result<TickerConfig>;
+/**
+ * argv that runs the ticker as its own process: `[runtime, route-ticker.main.ts, <config JSON>]`. The
+ * caller spawns it detached and stores the child's pid as an `OwnedProcess` with `recordCondition`, so
+ * COND-1 undo (`warden release`, gc) kills it.
+ */
+export declare function detachedTickerArgv(runtime: string, mainPath: string, config: TickerConfig): string[];

package/types/e2e/src/conditions/scheduler.d.ts

@@ -0,0 +1,83 @@
+import type { LocationCondition, NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { ConditionSink } from "./condition-events";
+import type { TickerClock } from "./route-ticker";
+export type StepResult = {
+    success: true;
+} | {
+    success: false;
+    error: {
+        message: string;
+    };
+};
+/** The slice of a `Driver` the scheduler drives. A driver satisfies it; the detached child builds a smaller one. */
+export type SchedulerTarget = {
+    network?(condition: NetworkCondition): Promise<StepResult>;
+    location?(op: LocationCondition): Promise<StepResult>;
+};
+export type SchedulerDeps = TickerClock & {
+    /** uniform [0, 1) for jitter; default is a generator seeded from `seed` */
+    rng?: () => number;
+    /** told about every transition that landed */
+    sink?: ConditionSink;
+};
+export type FlapOptions = {
+    upMs: number;
+    downMs: number;
+    /** each phase lasts its length +/- this percent, drawn from the seeded rng */
+    jitterPct?: number;
+    /** the "up" condition, default online; also what stop restores */
+    base?: NetworkCondition;
+    seed?: number;
+    /** false when the caller already put the device in `base`; the first phase then just waits */
+    applyInitial?: boolean;
+};
+export type TimelineStep = {
+    atMs: number;
+    network?: NetworkCondition;
+    location?: LocationCondition;
+};
+export type SchedulerOutcome = {
+    transitions: number;
+    stopped: "finished" | "aborted";
+} | {
+    transitions: number;
+    stopped: "failed";
+    error: string;
+};
+export type SchedulerStatus = {
+    state: "running";
+    transitions: number;
+    phase?: "up" | "down";
+    step?: number;
+} | {
+    state: "finished" | "stopped";
+    transitions: number;
+} | {
+    state: "failed";
+    transitions: number;
+    error: string;
+};
+export type Scheduler = {
+    /** idempotent; flap puts `base` back before `done` resolves, a timeline just stops */
+    stop(): void;
+    /** resolves with the outcome, never rejects */
+    done: Promise<SchedulerOutcome>;
+    current(): SchedulerStatus;
+};
+/** mulberry32: small, fast, and the same sequence for the same seed. */
+export declare function seededRng(seed: number): () => number;
+/**
+ * Alternates the network between `base` (up, `upMs`) and offline (down, `downMs`), each phase stretched or
+ * shrunk by up to `jitterPct` using a seeded rng, paced against the clock. Starts in the up phase. In this
+ * process: the driver holds the handle and stops it on the next network op or `close()`; a detached child runs
+ * the same loop (`scheduler.main.ts`). 3 failed transitions in a row end it as `failed`. However it ends, `base`
+ * is put back before `done` resolves (best effort when it ended on a failure).
+ */
+export declare function startFlap(target: SchedulerTarget, options: FlapOptions, deps: SchedulerDeps): Scheduler;
+/**
+ * Runs `steps` in `atMs` order (ties keep the given order), each at `atMs` after the start, paced against the
+ * clock. A step with both `network` and `location` applies the network first, then the location. A step counts
+ * as failed when either part fails; 3 failed steps in a row end it as `failed`. Stopping leaves the device as
+ * the last step left it (restoring is the spec API's job: it knows the previous conditions).
+ */
+export declare function startTimeline(target: SchedulerTarget, steps: readonly TimelineStep[], deps: SchedulerDeps): Scheduler;

package/types/e2e/src/device-a11y.d.ts

@@ -0,0 +1,97 @@
+import type { TextSize } from "../../core/src/conditions/conditions.types";
+import type { Result } from "../../types/src/result";
+import type { A11yAuditOptions, A11yAuditResult, A11yEventSource, Announcement, ScreenReaderState, SpokenLine } from "./a11y/a11y.types";
+import type { A11yTarget } from "./a11y/a11y-target";
+import type { Driver, DriverError, Snapshot } from "./driver/driver.types";
+import type { E2eEnv } from "./env";
+/** `device.a11yAudit(opts)`: the audit's own options, plus what only a device knows. */
+export type DeviceA11yAuditOptions = A11yAuditOptions & {
+    /** the text size the app runs at; `text-clipped` only runs from `accessibility-medium` up */
+    textSize?: TextSize;
+    /** also run the platform's own audit (XCUITest on iOS, ATF on Android) when the driver can. Default true. */
+    native?: boolean;
+};
+/** An announcement or live-region change the app made, in the order it happened. */
+export type A11yAnnouncement = {
+    kind: "announcement" | "live-region";
+    text: string;
+    /** epoch ms on the device */
+    at: number;
+    source: A11yEventSource;
+};
+export type A11yAnnouncementsOptions = {
+    /** cursor from an earlier read: only what came after it */
+    since?: number;
+};
+export type A11yAnnouncements = {
+    announcements: A11yAnnouncement[];
+    /** pass back as `since` to read only what is new */
+    cursor: number;
+    /** the Android event buffer overwrote events this caller never read */
+    lost?: boolean;
+};
+export type ScreenReaderSpokenOptions = {
+    since?: number;
+};
+/**
+ * What a screen reader does with the screen. `order()` is warden's model of the reading order and works on both
+ * platforms (every `Announcement` is `source: "simulated"`: an approximation, never what VoiceOver or TalkBack
+ * say). The other calls drive a real TalkBack on an Android emulator (`device.a11y({ screenReader: true })`) and
+ * throw `ACTION_FAILED` (`E_UNSUPPORTED`) anywhere else.
+ */
+export type DeviceScreenReader = {
+    /** reading order of the current screen */
+    order(): Promise<Announcement[]>;
+    state(): Promise<ScreenReaderState>;
+    /** moves screen-reader focus one step on; resolves what it now holds (`undefined` past the end) */
+    next(): Promise<Announcement | undefined>;
+    prev(): Promise<Announcement | undefined>;
+    /** double-tap on the focused node */
+    activate(): Promise<void>;
+    /** the node holding screen-reader focus, if any */
+    focused(): Promise<Announcement | undefined>;
+    /** what the reader said since `since`; `cursor` goes back in as the next `since` */
+    spoken(options?: ScreenReaderSpokenOptions): Promise<{
+        lines: SpokenLine[];
+        cursor: number;
+    }>;
+};
+export type DeviceA11y = {
+    /**
+     * Audits the current screen: warden's rules over the snapshot (with the iOS injected read merged in when the app
+     * runs with it) plus the platform's own audit when the driver offers one. The suite's `a11y` config
+     * (`warden.config.ts`) supplies the defaults; options passed here win key by key.
+     */
+    a11yAudit(options?: DeviceA11yAuditOptions): Promise<A11yAuditResult>;
+    readonly screenReader: DeviceScreenReader;
+    /** announcements and live-region changes since `since` (needs the injected library on iOS) */
+    announcements(options?: A11yAnnouncementsOptions): Promise<A11yAnnouncements>;
+};
+export type DeviceA11yDeps = {
+    driver: Driver;
+    env: Pick<E2eEnv, "a11yAudit" | "assertionTimeoutMs"> & {
+        bundleId?: string;
+    };
+    /** read per call: the runner swaps it for every attempt */
+    signal: () => AbortSignal | undefined;
+    step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+};
+/**
+ * The snapshot with the screen-reader facts a plain snapshot lacks merged in. A driver without the capability, or an
+ * app launched without the injected library (`E_UNSUPPORTED`), leaves it as it is. Any other failure is returned.
+ */
+export declare function withA11yRead(driver: Driver, snapshot: Snapshot): Promise<Result<Snapshot, DriverError>>;
+/** The screen as text with the `--a11y` columns: what an a11y failure attaches as `screen-at-failure.txt`. */
+export declare function renderA11yScreen(snapshot: Snapshot, maxLines?: number): string;
+export type AuditSnapshotOptions = DeviceA11yAuditOptions & {
+    /** the app the platform's own audit checks (iOS XCUITest) */
+    bundleId?: string;
+};
+/**
+ * Audits one snapshot: warden's rules, plus the platform's own audit (XCUITest / ATF) unless `native: false`, `rules`
+ * leaves out `native`, or the driver has none. `device.a11yAudit` and `warden ui a11y audit` share this.
+ */
+export declare function auditSnapshot(driver: Driver, snapshot: Snapshot, options?: AuditSnapshotOptions): Promise<A11yAuditResult>;
+export declare function createDeviceA11y(deps: DeviceA11yDeps): DeviceA11y & {
+    target: A11yTarget;
+};

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

@@ -1,5 +1,8 @@
+import { type ConditionRun, type DeviceCamera, type DeviceClock, type DeviceConditions, type DeviceLocation, type DeviceNetwork, type DevicePermissions, type TimelineStepInput } from "./conditions/device-conditions";
+import { type ConditionRecorder } from "./conditions/lease-recorder";
+import { type DeviceA11y } from "./device-a11y";
 import { type DeviceDevtools } from "./device-devtools";
-import type { Driver, Orientation } from "./driver/driver.types";
+import type { BiometricState, Driver, Orientation } from "./driver/driver.types";
 import { type SettleDetail } from "./driver/settle";
 import type { E2eEnv } from "./env";
 import { type Clock, type FixtureSession } from "./fixture-session";
@@ -22,6 +25,8 @@ export type OpenLinkOptions = {
 };
 export type SnapshotTextOptions = {
     interactiveOnly?: boolean;
+    /** append hint, actions, focus and live-region facts to each line (the iOS injected read is merged in when available) */
+    a11y?: boolean;
 };
 export type SettleOptions = {
     /** how long the UI must stay unchanged. Default 250 ms. */
@@ -29,12 +34,33 @@ export type SettleOptions = {
     /** give up after this long. Default 3000 ms. */
     timeout?: number;
 };
-export type Device = {
+export type { BiometricState };
+/**
+ * Simulated Face ID / Touch ID / fingerprint (simulators and emulators only). Every method answers the state after the op.
+ * iOS: the first prompt per app shows an "Allow X to use Face ID?" alert; answer it with `device.alert("accept")`.
+ * Enroll before installing or launching the app: a new enrollment invalidates biometry-bound keys.
+ * Android: `enroll` / `unenroll` throw `ACTION_FAILED` (driver `E_UNSUPPORTED`); enrollment comes from the golden snapshot, so set
+ * the profile's `biometrics: true`.
+ */
+export type DeviceBiometrics = {
+    status(): Promise<BiometricState>;
+    /** iOS: enrolls Face ID / Touch ID. Android: unsupported, use profile `biometrics: true`. */
+    enroll(): Promise<BiometricState>;
+    /** iOS: removes the enrollment. Android: unsupported. */
+    unenroll(): Promise<BiometricState>;
+    /** Presents a matching face / finger to the pending prompt. */
+    match(): Promise<BiometricState>;
+    /** Presents a non-matching face / finger to the pending prompt. */
+    fail(): Promise<BiometricState>;
+};
+export type Device = DeviceA11y & {
     /**
      * Answers the system alert / sheet on top. `accept` presses the first present of OK, Allow, Open,
      * Continue, Yes, Done, Allow While Using App, Allow Once (else the last button); `dismiss` the first
      * of Cancel, Don't Allow, Not Now, Dismiss, No, Close (else the first button); `{button}` the button
-     * with that name (`ACTION_FAILED` when absent). Resolves false when no alert is showing.
+     * with that name (`ACTION_FAILED` when absent). The Android autofill "Save password?" sheet is closed with Back for
+     * `accept` and `dismiss` alike (never its Never / Continue buttons, which write to the user's account). Resolves false
+     * when no alert is showing.
      */
     alert(action: AlertAction): Promise<boolean>;
     /**
@@ -50,6 +76,8 @@ export type Device = {
     back(): Promise<void>;
     orientation(set?: Orientation): Promise<Orientation>;
     appearance(set?: "light" | "dark"): Promise<"light" | "dark">;
+    /** Simulated biometrics: `status`, `enroll`, `unenroll`, `match`, `fail`; see {@link DeviceBiometrics}. */
+    readonly biometrics: DeviceBiometrics;
     clipboard(): Promise<string>;
     setClipboard(text: string): Promise<void>;
     /**
@@ -78,6 +106,37 @@ export type Device = {
      * typed report. The report is copied under the attempt's `perf/`; budgets from `warden.config.ts` fail `stop`.
      */
     readonly perf: DevicePerf;
+    /**
+     * Network conditions: `set("offline" | "3g" | …)`, `during`, `flap`, `fault`, `status`, `reset`. Everything a test
+     * changes is put back when it ends, to the suite's `conditions` (`warden.config.ts`).
+     */
+    readonly network: DeviceNetwork;
+    /** Simulated location: `set`, `route`, `scenario`, `clear`. Put back when the test ends. */
+    readonly location: DeviceLocation;
+    /** The device's wall clock: `set`, `advance("2d")`, `during`, `reset`. Needs a driver with a clock op. */
+    readonly clock: DeviceClock;
+    /** Runtime permissions of the app: `set({ location: "denied", camera: "granted" })`, `reset`. Set before `app.open()`. */
+    readonly permissions: DevicePermissions;
+    /** Device timezone (`"Asia/Tokyo"`, `null` resets). iOS: for the app launched next. */
+    timezone: DeviceConditions["timezone"];
+    /** The app's locale (`"fr-FR"`, `null` resets). iOS: for the app launched next. Android 13+. */
+    locale: DeviceConditions["locale"];
+    /** Text size, bold text, contrast, reduce motion (`null` resets); the result names what the platform skipped. */
+    a11y: DeviceConditions["a11y"];
+    /** Battery level and charging: real on Android emulators, status bar only on iOS (`cosmetic: true`). */
+    battery: DeviceConditions["battery"];
+    /**
+     * Simulated camera: `set("fixtures/qr.png", { facing })`, `clear`, `status`. The asset (png, jpg, heic, mp4, mov; path relative
+     * to the spec file) plays in the app's real camera. iOS: live in an app launched with the camera, else from the next launch.
+     * Android: a `--camera` device; an image shows on the next camera open, a video feed reboots the emulator.
+     */
+    readonly camera: DeviceCamera;
+    /** Android: a critical trim-memory signal to the app. iOS: `E_UNSUPPORTED`. */
+    memoryWarning: DeviceConditions["memoryWarning"];
+    /** iOS: delivers an APNs payload to the app. Android: `E_UNSUPPORTED`. */
+    push: DeviceConditions["push"];
+    /** Applies network and location changes at times from now; stopped when the test ends. */
+    timeline(steps: readonly TimelineStepInput[]): Promise<ConditionRun>;
 };
 export type DeviceDeps = {
     session: FixtureSession;
@@ -86,5 +145,9 @@ export type DeviceDeps = {
     clock?: Clock;
     /** runs `warden …` for `device.perf`; default spawns `WARDEN_BIN` */
     perfExec?: PerfExec;
+    /** shared with `app` so a launch knows to load the network dylib; default: made here */
+    conditions?: DeviceConditions;
 };
-export declare function createDevice({ session, driver, env, clock, perfExec }: DeviceDeps): Device;
+export declare function createDevice({ session, driver, env, clock, perfExec, conditions, }: DeviceDeps): Device;
+/** The conditions of one attempt's device: events go to the session's `results.jsonl`, calls honour its signal. */
+export declare function createSessionConditions(session: FixtureSession, driver: Driver, env: E2eEnv, recorder?: ConditionRecorder | undefined): DeviceConditions;