@delacour/warden-e2e 0.5.0 → 0.7.0

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

@@ -0,0 +1,170 @@
+import { type NetworkInput } from "../../../core/src/conditions/conditions.config";
+import type { ClockCondition, HostFault, LatLon, LocationCondition, LocationScenario, NetworkCondition } from "../../../core/src/conditions/conditions.types";
+import type { A11yOp, A11yState, BatteryOp, BatteryState, 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;
+};
+export type DeviceConditions = {
+    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;
+};
+/** 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.d.ts

@@ -1,5 +1,7 @@
+import { type ConditionRun, 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 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";
@@ -29,12 +31,33 @@ export type SettleOptions = {
     /** give up after this long. Default 3000 ms. */
     timeout?: number;
 };
+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 = {
     /**
      * 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 +73,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 +103,31 @@ 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"];
+    /** 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 +136,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;

package/types/e2e/src/driver/android/android-app.d.ts

@@ -9,6 +9,10 @@ export type AppDeps = {
     log?: Logger;
     /** the app under test: `openUrl` is addressed to it (`am start -p`) so no other handler or chooser can take the link */
     appPackage?: string;
+    /** a real phone: `uninstall` and `clearData` only touch `appPackage` and `ownedPackages` (`E_REFUSED` otherwise) */
+    physical?: boolean;
+    /** packages warden installed on this device besides `appPackage` */
+    ownedPackages?: readonly string[];
     /** how long `am start -W` may wait for the first frame (default `START_WAIT_TIMEOUT_MS`); tests shorten it */
     startWaitTimeoutMs?: number;
     /** how long the `pidof` after a timed-out start may take (default `START_PROBE_TIMEOUT_MS`); tests shorten it */

package/types/e2e/src/driver/android/android-argv.d.ts

@@ -1,3 +1,4 @@
+import type { LatLon } from "../../../../core/src/conditions/conditions.types";
 import type { Result } from "../../../../types/src/result";
 import type { DriverError, HardwareButton, KeyName, Point } from "../driver.types";
 import type { GesturePlan } from "../gesture-geometry";
@@ -14,6 +15,13 @@ export type MotionAction = "DOWN" | "MOVE" | "UP" | "CANCEL";
 export declare function motionEventArgv(action: MotionAction, point: Point): string[];
 /** Lowest sdk with `input motionevent` (Android 8.0). */
 export declare const MOTIONEVENT_MIN_SDK = 26;
+/** Host-side `adb -s <serial> emu finger touch <id>`: the emulator console presents fingerprint `id` to the sensor. */
+export declare function emuFingerTouchArgv(adb: string, serial: string, fingerId: number): string[];
+/** An id no enrollment holds: the emulator reports a non-matching touch. */
+export declare const UNENROLLED_FINGER_ID = 99;
+export declare function dumpsysFingerprintArgv(): string[];
+/** Emulator serials (`emulator-5554`); the console commands exist nowhere else. */
+export declare const isEmulatorSerial: (serial: string) => boolean;
 /** `input keycombination` (and so select-all by Ctrl+A) exists from Android 13. */
 export declare const SELECT_ALL_MIN_SDK = 33;
 export declare const DRAG_STEPS = 8;
@@ -104,6 +112,17 @@ export declare function dumpTtyHostArgv(adb: string, serial: string): string[];
 export declare function dumpFileCommand(path?: string): string;
 /** Host argv: `adb -s <serial> install -r <apk>`. */
 export declare function installArgv(adb: string, serial: string, apkPath: string): string[];
+/**
+ * Host argv: `adb -s <serial> emu geo fix <lon> <lat> [alt]`. The emulator console takes LONGITUDE first,
+ * the reverse of `simctl location set lat,lon` and of everything else here.
+ */
+export declare function geoFixArgv(adb: string, serial: string, point: LatLon, altM?: number): string[];
+/** `adb emu` exits 0 even when the console answers `KO: …`; the reason, or undefined when it took. */
+export declare function geoFixFailure(res: {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}): string | undefined;
 export declare function uninstallArgv(adb: string, serial: string, packageName: string): string[];
 /** Exit 0 and `package:/…` when installed, exit 1 and nothing otherwise. */
 export declare function pmPathArgv(packageName: string): string[];

package/types/e2e/src/driver/android/android-clock.d.ts

@@ -0,0 +1,28 @@
+import type { ClockCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Exec } from "../../../../core/src/exec";
+import type { ClockState, DriverResult } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+/**
+ * Android mock clock: system time, device-wide. `settings put global auto_time 0` stops the network time sync from
+ * undoing it, `cmd alarm set-time <epoch ms>` sets it (a shell-uid command on emulator images, verified on the
+ * device's own `date`); where that does not take, `adb root` + `date -s @<secs>`. `real` is the undo in
+ * `core/conditions/undo.ts`: `auto_time 1` then the host's time. There is no way to freeze Android's clock, so
+ * `frozen` is `E_UNSUPPORTED`. Monotonic clocks are not affected by a wall-clock set.
+ */
+export declare const AUTO_TIME_OFF_ARGV: readonly string[];
+export declare const AUTO_TIME_ON_ARGV: readonly string[];
+export declare const DATE_ARGV: readonly string[];
+export declare const setTimeArgv: (epochMs: number) => string[];
+/** How far the device's `date` may be from the target (it only reports whole seconds, and a call takes time). */
+export declare const CLOCK_TOLERANCE_MS = 5000;
+export type AndroidClockDeps = {
+    session: AdbSession;
+    /** host runner for the `adb root` fallback */
+    exec: Exec;
+    adb: string;
+    serial: string;
+    /** host wall time, ms (default `Date.now`) */
+    wallNow?: () => number;
+};
+/** Put the emulator's wall clock at `condition`; reads it back and fails with `E_IO` when it did not move. */
+export declare function applyAndroidClock(deps: AndroidClockDeps, condition: ClockCondition): DriverResult<ClockState>;

package/types/e2e/src/driver/android/android-device.d.ts

@@ -1,6 +1,7 @@
 import type { DriverResult, Logger, Orientation, ScreenInfo } from "../driver.types";
 import type { AdbSession } from "./adb-session";
 import { type RotationValue } from "./android-argv";
+import { type PhoneFacts } from "./android-phone";
 /** Device facts read once at open: boot flag, screen size/density. Pure parsers + small session helpers. */
 export declare const BOOT_TIMEOUT_MS = 30000;
 export type Clock = {
@@ -15,11 +16,18 @@ export declare function parseWmSize(text: string): {
 } | undefined;
 /** `wm density`: `Physical density: 420` / `Override density: 320`; scale = dpi / 160. */
 export declare function parseWmDensity(text: string): number | undefined;
+/**
+ * The probe for `serial`. A console `emulator-N` is an emulator by construction. Anything else (a phone, or a
+ * network emulator) also reads the qemu props, wakefulness and keyguard, in the same round trip.
+ */
+export declare function bootProbeFor(serial: string): string;
 /** The sdk level on the probe's second line, if numeric. */
 export declare function sdkFromProbe(stdout: string): number | undefined;
+/** `physical`: set only for a real phone (its qemu props are empty); an emulator, or an unprobed serial, has none. */
 export type BootInfo = {
     screen: ScreenInfo | undefined;
     sdk: number | undefined;
+    physical: PhoneFacts | undefined;
 };
 /** The screen out of a boot probe's output, if `wm` answered. */
 export declare function screenFromProbe(stdout: string): ScreenInfo | undefined;