@delacour/warden-e2e 0.7.0 → 0.9.0

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

@@ -1,5 +1,6 @@
-import { type ConditionRun, type DeviceClock, type DeviceConditions, type DeviceLocation, type DeviceNetwork, type DevicePermissions, type TimelineStepInput } from "./conditions/device-conditions";
+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 { BiometricState, Driver, Orientation } from "./driver/driver.types";
 import { type SettleDetail } from "./driver/settle";
@@ -24,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. */
@@ -50,7 +53,7 @@ export type DeviceBiometrics = {
     /** Presents a non-matching face / finger to the pending prompt. */
     fail(): Promise<BiometricState>;
 };
-export type Device = {
+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
@@ -122,6 +125,12 @@ export type Device = {
     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`. */

package/types/e2e/src/driver/a11y-events.d.ts

@@ -0,0 +1,30 @@
+import type { Result } from "../../../types/src/result";
+import type { A11yEvent, A11yEventSource } from "../a11y/a11y.types";
+import type { Driver, DriverResult } from "./driver.types";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `ReadsA11y`): the announcements, live-region
+ * changes and screen/layout notifications an app emitted since `since`. `cursor` is opaque to callers: pass the last
+ * one back to get only what is new (Android: the server's sequence number; iOS: a byte offset into the inject events
+ * file). `since` omitted reads from the start. `lost` is set when the Android ring overwrote events the caller never saw.
+ * iOS needs the app launched with the injected library (`WARDEN_A11Y=1` / the `a11y` option) and answers
+ * `E_UNSUPPORTED` otherwise.
+ */
+export type A11yEventsRead = {
+    events: A11yEvent[];
+    cursor: number;
+    lost?: boolean;
+};
+export type ReadsA11yEvents = {
+    a11yEvents(since?: number): DriverResult<A11yEventsRead>;
+};
+export declare function canReadA11yEvents(driver: Driver): driver is Driver & ReadsA11yEvents;
+export declare function parseA11yEvent(value: unknown, source: A11yEventSource): A11yEvent | undefined;
+/** The `a11yEvents` reply of `warden-uiad`: `{events:[{kind,text,at}], cursor, lost?}`. */
+export declare function parseUiadA11yEvents(data: unknown): Result<A11yEventsRead, string>;
+/**
+ * The injected library's `<state>.events` file (JSON lines, append-only) from byte offset `since`. Only lines that end
+ * in a newline count: a half-written tail stays unread and the returned cursor stops before it, so the next read
+ * starts there. A malformed complete line is skipped (the cursor moves past it). A `since` beyond the file (the file
+ * was reset by a relaunch) restarts from 0.
+ */
+export declare function parseInjectEvents(text: string, since?: number): A11yEventsRead;

package/types/e2e/src/driver/a11y-read.d.ts

@@ -0,0 +1,12 @@
+import type { Driver, DriverResult, Snapshot } from "./driver.types";
+/**
+ * Optional capability next to the frozen `Driver` interface (pattern: `RepeatingKeys` in `typing.ts`): read the
+ * screen-reader facts a plain snapshot lacks and return the snapshot with `Element.a11y` filled in. iOS: the injected
+ * dylib's UIKit walk merged by identifier / frame (`ios/ios-a11y.ts`); needs the app launched with the dylib
+ * (`WARDEN_A11Y=1` or the `a11y` driver option) and answers `E_UNSUPPORTED` otherwise. Android has no such driver
+ * method: `warden-uiad` snapshots carry `a11y` already.
+ */
+export type ReadsA11y = {
+    readA11y(snapshot: Snapshot): DriverResult<Snapshot>;
+};
+export declare function canReadA11y(driver: Driver): driver is Driver & ReadsA11y;

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

@@ -12,6 +12,8 @@ import { type AndroidStateStore } from "./android-state";
 export type AnimationGuard = {
     /** put the scales back (once); a restore that fails leaves the saved originals for the next driver */
     restore(): Promise<void>;
+    /** the transition scale the device had before it was zeroed (`"null"` = never set); undefined when it was off already */
+    transitionOriginal(): string | undefined;
 };
 export type AnimationDeps = {
     session: AdbSession;
@@ -25,5 +27,10 @@ export type AnimationDeps = {
 /**
  * One shell round trip that reads the three scales and sets them to 0, then (when something has to be put
  * back) saves the originals. Never fails the open: a device that refuses just keeps its animations.
+ *
+ * The transition scale is the exception: RN (0.86) reads it as "reduce motion", and zero would make every app
+ * under test report reduce-motion on. It goes straight back to the device's own value, so only the window and
+ * animator scales stay at 0 (those are what makes the run fast and stable); `a11y({ reduceMotion: true })` zeroes it
+ * on request.
  */
 export declare function disableAnimations(deps: AnimationDeps): Promise<AnimationGuard>;

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

@@ -93,6 +93,8 @@ export declare function animationScaleArgvs(): string[][];
 export declare function animationReadArgvs(): string[][];
 /** Put saved scales back: a value is `put` again, a setting that was never set (`null`) is deleted. */
 export declare function animationRestoreArgvs(values: AnimationValues): string[][];
+/** Put just the transition scale back (a setting that was never set, `null`, is deleted). */
+export declare function transitionRestoreArgv(value: string): string[];
 /** Host argv: `adb -s <serial> exec-out screencap -p` (binary PNG on stdout). */
 export declare function screencapArgv(adb: string, serial: string): string[];
 /** `getprop <key>` (boot flag, sdk level, model). */

package/types/e2e/src/driver/android/android-camera-host.d.ts

@@ -0,0 +1,23 @@
+import { type Exec } from "../../../../core/src/exec";
+import type { DeviceProvider } from "../../../../core/src/providers/provider.types";
+import type { Store } from "../../../../core/src/store";
+import { type Result } from "../../../../types/src/result";
+import type { AndroidCameraDeps } from "./android-camera";
+export type AndroidCameraHostOptions = {
+    serial: string;
+    env?: Record<string, string | undefined>;
+    exec?: Exec;
+    now?: () => number;
+    /** the lease store (default: the process's shared connection) */
+    store?: () => Result<Store>;
+    /** the Android provider (default: a real one on `adb` / `emulator`) */
+    provider?: (store: Store) => DeviceProvider;
+};
+/** What `createAndroidCamera` needs from warden's state: the device's recorded profile, a restart, the lease record. */
+export type AndroidCameraHost = Pick<AndroidCameraDeps, "profile" | "relaunch"> & Required<Pick<AndroidCameraDeps, "record">>;
+/**
+ * The camera driver's view of warden's store and provider, opened lazily: a run that never touches the camera never
+ * opens either. The profile (`<avd>+cam`) is what the claim recorded for the serial; a restart goes through the same
+ * provider that launched the emulator, so the serial, console port, device record and lease stay.
+ */
+export declare function createAndroidCameraHost(options: AndroidCameraHostOptions): AndroidCameraHost;

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

@@ -0,0 +1,28 @@
+import { type CameraCondition } from "../../../../core/src/conditions/conditions.types";
+import type { Exec } from "../../../../core/src/exec";
+import type { Driver } from "../driver.types";
+export type AndroidCameraDeps = {
+    serial: string;
+    wardenHome: string;
+    /** host process runner: `sips` re-encodes images to PNG */
+    exec: Exec;
+    /** the profile warden recorded for this device (`pixel-10+cam`); undefined = not a warden device */
+    profile: () => string | undefined;
+    /** restart the emulator on its own serial through the provider and wait until it is ready */
+    relaunch: () => Promise<{
+        success: true;
+        data: undefined;
+    } | {
+        success: false;
+        error: string;
+    }>;
+    /** told the feeds now playing, so the lease carries the `camera` area and release undoes it */
+    record?: (feeds: CameraCondition) => void;
+};
+/**
+ * The Android emulator camera. `-camera-back` / `-camera-front` name a file the emulator re-reads whenever an app
+ * opens the camera, so an image swap is an atomic file replace (`appliesOnCameraOpen`). Only PNG renders, so every
+ * other image is re-encoded with `sips`. The source TYPE (image or video) is fixed at launch: a change of it is
+ * recorded in `mode.json` and the emulator is restarted on the same serial (`rebooted`).
+ */
+export declare function createAndroidCamera(deps: AndroidCameraDeps): Driver["camera"];

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

@@ -5,6 +5,7 @@ import type { ClockRecorder } from "../clock-recorder";
 import type { Driver, DriverResult, Element, Logger, Point, ScreenInfo } from "../driver.types";
 import type { NetworkProxyPort } from "../network-proxy";
 import { type SpawnAdb } from "./adb-session";
+import { type AndroidCameraHost } from "./android-camera-host";
 import { type Clock } from "./android-device";
 import { type DumpRoute } from "./android-dump";
 import { type AndroidStateStore } from "./android-state";
@@ -65,6 +66,10 @@ export type AndroidDriverOptions = {
     tickerClock?: TickerClock;
     /** told about every network flap transition (the `condition` events of `results.jsonl`) */
     conditionSink?: ConditionSink;
+    /** warden's home, where a camera emulator's feeds live (default `$WARDEN_HOME`, else `~/.warden`) */
+    wardenHome?: string;
+    /** the camera op's view of warden's store and provider (default: the real ones, opened on first use) */
+    cameraHost?: AndroidCameraHost;
 };
 /** Deepest hittable element containing `point` (later in preorder wins ties: drawn on top); else deepest any. */
 export declare function elementAt(flat: readonly Element[], point: Point): Element | null;

package/types/e2e/src/driver/android/android-screen-reader.d.ts

@@ -0,0 +1,23 @@
+import type { Driver } from "../driver.types";
+import type { ActsOnElements } from "../element-actions";
+import type { DrivesScreenReader } from "../screen-reader";
+import type { AdbSession } from "./adb-session";
+import type { Clock } from "./android-device";
+import type { TalkBackControl } from "./android-talkback";
+import type { UiadOps } from "./uiad-ops";
+/**
+ * The Android driver while TalkBack is on (WDN-A11Y, A11Y-7): the `DrivesScreenReader` calls, and the element actions
+ * that replace touches. With TalkBack on a tap only moves its focus and a one-finger swipe navigates, so a locator tap
+ * is `ACTION_CLICK` on the node and a locator scroll is `ACTION_SCROLL_*` on its scrollable (server ops, no touch).
+ * Raw coordinate taps never come through here and stay touches: with TalkBack on they move its focus, and whether that
+ * also activates depends on its "single-tap to activate" setting.
+ */
+export type ScreenReaderDeps = {
+    uiad: UiadOps | undefined;
+    talkback: TalkBackControl;
+    session: AdbSession;
+    clock: Clock;
+    /** a touch, for the focus-then-double-tap fallback */
+    tap: Driver["tap"];
+};
+export declare function createScreenReaderOps(deps: ScreenReaderDeps): DrivesScreenReader & ActsOnElements;

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

@@ -1,6 +1,7 @@
 import type { PermissionName, PermissionState } from "../../../../core/src/conditions/conditions.types";
 import type { Driver } from "../driver.types";
 import type { AdbSession } from "./adb-session";
+import { type TalkBackControl } from "./android-talkback";
 /** Permission name to the manifest permissions it covers; a name absent here is skipped with the reason in `ANDROID_NO_PERMISSION`. */
 export declare const ANDROID_PERMISSIONS: Partial<Record<PermissionName, readonly string[]>>;
 export declare const ANDROID_NO_PERMISSION: Partial<Record<PermissionName, string>>;
@@ -11,7 +12,7 @@ export declare const setTimezoneArgv: (tz: string) => string[];
 export declare const TIMEZONE_PROP_ARGV: readonly string[];
 export declare const setAppLocaleArgv: (pkg: string, tag: string | null) => string[];
 export declare const getAppLocaleArgv: (pkg: string) => string[];
-export declare const settingGetArgv: (table: "system" | "secure", key: string) => string[];
+export declare const settingGetArgv: (table: "system" | "secure" | "global", key: string) => string[];
 export declare const BOLD_TEXT_ADJUSTMENT = 300;
 export declare const trimMemoryArgv: (pkg: string) => string[];
 export declare const BATTERY_RESET_ARGV: readonly string[];
@@ -29,6 +30,12 @@ export type AndroidSettingsDeps = {
     sleep?: (ms: number) => Promise<void>;
     /** the host's timezone, restored on `timezone(null)` when no previous one is given (default: `Intl`) */
     hostTimezone?: () => string;
+    /** the transition animation scale the device had before the driver zeroed it (what `reduceMotion: false` restores); `"null"` / absent = none known */
+    transitionOriginal?: () => string | undefined;
+    /** is `warden-uiad` how this driver reads the screen (TalkBack mode needs it: the dump fallback unbinds TalkBack); default false */
+    uiadAvailable?: () => boolean;
 };
 export type AndroidSettings = Pick<Driver, "permissions" | "timezone" | "locale" | "a11y" | "battery" | "memoryWarning" | "push">;
-export declare function createAndroidSettings(deps: AndroidSettingsDeps): AndroidSettings;
+export declare function createAndroidSettings(deps: AndroidSettingsDeps): AndroidSettings & {
+    talkback: TalkBackControl;
+};

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

@@ -0,0 +1,18 @@
+import type { DriverResult } from "../driver.types";
+import type { SpokenRead } from "../screen-reader";
+import type { SrEventsRead } from "./uiad-screen-reader";
+/**
+ * What TalkBack said since a cursor (`DrivesScreenReader.screenReaderSpoken`). The cursor is the device epoch ms of the
+ * last line returned, whichever source it came from. Real speech needs TalkBack's verbose log (a developer setting
+ * only its UI can change); without it the lines are composed by the speech model from the focus events the
+ * screen-reader stream saw, labelled `simulated`. Whichever the log allows is used for the whole read, never a mix.
+ */
+export type SpokenDeps = {
+    /** TalkBack's log, epoch timestamps (`TALKBACK_LOGCAT_ARGV`); undefined when it cannot be read */
+    readLog(): Promise<string | undefined>;
+    /** focus moves since 0 (the ring is small) */
+    focusEvents(): DriverResult<SrEventsRead>;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare function readSpoken(deps: SpokenDeps, since?: number): DriverResult<SpokenRead>;

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

@@ -0,0 +1,57 @@
+import type { ScreenReaderState } from "../../a11y/a11y.types";
+import type { DriverResult } from "../driver.types";
+/**
+ * TalkBack as the screen reader of an Android emulator (WDN-A11Y, A11Y-7). Everything is shell: the two secure settings
+ * that switch an accessibility service on, `pm` for presence and the notification grant, `dumpsys accessibility` to
+ * see that the service is bound (enabled in settings is not running: a UiAutomation client connected without
+ * `FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES` unbinds it). The previous values of both settings are kept so turning
+ * TalkBack off, or the lease's undo, puts back exactly what was there.
+ */
+export declare const TALKBACK_PACKAGE = "com.google.android.marvin.talkback";
+export declare const TALKBACK_SERVICE = "com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService";
+export declare const POST_NOTIFICATIONS = "android.permission.POST_NOTIFICATIONS";
+export declare const talkbackPathArgv: readonly string[];
+export declare const talkbackGrantArgv: readonly string[];
+export declare const accessibilityDumpArgv: readonly string[];
+export declare const secureGetArgv: (key: string) => string[];
+/** Set a secure key, or delete it when `value` is null (it was unset). The driver's shell quotes each argument. */
+export declare const secureWriteArgv: (key: string, value: string | null) => string[];
+/** `settings get` answers the text `null` for an unset key. */
+export declare function settingValue(stdout: string): string | null;
+/** `services` with the TalkBack component added after whatever is there (`:` separated, once). */
+export declare function withTalkBack(services: string | null): string;
+/** Is a TalkBack service among the bound ones in `dumpsys accessibility`? */
+export declare function talkbackBound(dump: string): boolean;
+export type Previous = {
+    services: string | null;
+    enabled: string | null;
+};
+type Shelled = {
+    ok: boolean;
+    stdout: string;
+    failure: string | undefined;
+};
+export type TalkBackDeps = {
+    serial: string;
+    shell(argv: readonly string[]): Promise<Shelled>;
+    must(argv: readonly string[]): DriverResult<string>;
+    /** is `warden-uiad` the way this driver reads the screen (the dump unbinds TalkBack) */
+    uiadAvailable(): boolean;
+    sleep(ms: number): Promise<void>;
+};
+export type TalkBackControl = {
+    /** warden turned TalkBack on and has not turned it off */
+    active(): boolean;
+    /** TalkBack is the screen reader now: warden's doing, or found already on and bound by `detect` */
+    on(): boolean;
+    /** read the device once (`fresh`: again, for a TalkBack another process turned on since) for a TalkBack that was on before warden touched anything (a crashed run, a person) */
+    detect(fresh?: boolean): Promise<boolean>;
+    state(): ScreenReaderState;
+    previous(): Previous | undefined;
+    enable(): DriverResult<ScreenReaderState>;
+    disable(): DriverResult<ScreenReaderState>;
+    /** is the service bound right now */
+    bound(): Promise<boolean>;
+};
+export declare function createTalkBack(deps: TalkBackDeps): TalkBackControl;
+export {};

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

@@ -0,0 +1,23 @@
+import type { DriverResult, Logger } from "../driver.types";
+import type { AdbSession } from "./adb-session";
+import { type PushDex } from "./uiad-device";
+/**
+ * `warden-atf.jar` (the Accessibility Test Framework, ~180 KB) goes to the device on the first audit only, named by its
+ * hash like the uiad dex, so a new build is a new file and the always-pushed uiad dex stays small.
+ */
+export type AtfJar = {
+    bytes: number;
+    jarSha256: string;
+    base64: string;
+};
+export declare function atfDevicePath(jar?: Pick<AtfJar, "jarSha256">): string;
+export type EnsureAtfDeps = {
+    session: AdbSession;
+    adb: string;
+    serial: string;
+    push?: PushDex;
+    jar?: AtfJar;
+    log?: Logger;
+};
+/** The jar is on the device (written now if it was not); the result is its path. */
+export declare function ensureAtfJar(deps: EnsureAtfDeps): DriverResult<string>;