@delacour/warden-e2e 0.0.0-stage → 0.1.1

package/types/e2e/src/driver/gesture-geometry.d.ts

@@ -0,0 +1,48 @@
+import type { Result } from "../../../types/src/result";
+import type { DriverError, GestureOptions, Point, TouchPath, TwoFingerOptions } from "./driver.types";
+/**
+ * Touch-path geometry shared by both drivers: `gesture`, `pinch` and `rotate` all become a `GesturePlan`, one
+ * frame per ~16 ms on a shared timeline, which `warden-simd` (`gesture` op) and `warden-uiad` (`gesture` op)
+ * only replay. Fingers go down together on the first frame and lift together after the last one (the iOS
+ * transports carry one phase for both contacts), so every path has the same frame count.
+ */
+export declare const GESTURE_FRAME_MS = 16;
+export declare const GESTURE_MAX_FRAMES = 1000;
+export declare const GESTURE_MAX_MS = 60000;
+export declare const GESTURE_MAX_POINTERS = 2;
+export declare const DEFAULT_GESTURE_MS = 300;
+export declare const DEFAULT_PINCH_MS = 400;
+export declare const DEFAULT_ROTATE_MS = 500;
+/** finger distance from the centre: points on iOS; Android multiplies by the screen scale */
+export declare const DEFAULT_RADIUS = 100;
+/** two-finger gestures rest at their end before lifting, so recognisers read ~0 velocity */
+export declare const TWO_FINGER_RELEASE_MS = 50;
+/** What the native servers replay: frame `k` of every path is `holdMs + k * frameMs` after touch-down. */
+export type GesturePlan = {
+    paths: Point[][];
+    frameMs: number;
+    holdMs: number;
+    releaseMs: number;
+    totalMs: number;
+};
+export type TwoFingerSpec = {
+    radius: number;
+    angle?: number;
+    scale?: number;
+    degrees?: number;
+};
+/**
+ * Validates 1–2 finger paths and resamples them onto one timeline. Bad input is `E_BAD_REQUEST`; more fingers
+ * than the driver takes is `E_UNSUPPORTED`.
+ */
+export declare function planGesture(paths: readonly TouchPath[], opts: GestureOptions | undefined, maxPointers: 0 | 1 | 2): Result<GesturePlan, DriverError>;
+/**
+ * Two fingers `radius` either side of `center` on an axis at `angle` degrees (0 = horizontal; finger 1 on the
+ * negative side), spreading to `radius * scale` and turning `degrees` clockwise (screen space, y down) over
+ * `durationMs`. A turn is sampled every few degrees so the fingers follow the arc.
+ */
+export declare function twoFingerPaths(center: Point, spec: TwoFingerSpec, durationMs: number): [TouchPath, TouchPath];
+/** Two fingers spreading (`scale` > 1) or closing (< 1) around `center`. */
+export declare function pinchPlan(center: Point, scale: number, opts: TwoFingerOptions | undefined, defaultRadius: number): Result<GesturePlan, DriverError>;
+/** Two fingers turning `degrees` around `center`; positive is clockwise on screen. */
+export declare function rotatePlan(center: Point, degrees: number, opts: TwoFingerOptions | undefined, defaultRadius: number): Result<GesturePlan, DriverError>;

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

@@ -0,0 +1,63 @@
+import type { Exec } from "../../../../core/src/exec";
+import type { E2eEnv } from "../../env";
+import type { ProbesFrontmost, ReadsAlertOn } from "../alerts";
+import type { Driver, DriverResult, KeyName, Logger } from "../driver.types";
+import type { SelectsAll } from "../typing";
+import { type SwappableClient } from "./ios-session";
+import { type Simctl } from "./simctl";
+import { type SimdClient } from "./simd-client";
+import type { SimdSpawn } from "./simd-transport";
+/**
+ * The iOS `Driver`: input and AX through `warden-simd` (socket when `WARDEN_SIMD_SOCKET` is set, else a
+ * helper spawned on stdio), app lifecycle / clipboard / appearance through `xcrun simctl`. Fallbacks:
+ * `typeText` pastes what the HID keyboard map cannot type, `settle` polls snapshot hashes when the
+ * helper has no native quiescence, `screenshot` uses `simctl io` when the helper cannot.
+ */
+export type IosDriverEnv = Pick<E2eEnv, "simd" | "simdSocket" | "helperDir">;
+/** The iOS driver is a `Driver` plus the optional capabilities of `driver/alerts.ts`. */
+export type IosDriver = Driver & SelectsAll & ReadsAlertOn & ProbesFrontmost;
+export type OpenIosDriverOptions = {
+    udid: string;
+    env?: IosDriverEnv;
+    exec: Exec;
+    spawn?: SimdSpawn;
+    log?: Logger;
+    /** explicit helper binary (skips {@link locateHelper}) */
+    helperPath?: string;
+    /** explicit helper socket (wins over `env.simdSocket`) */
+    socketPath?: string;
+    /**
+     * An already connected (handshaken) helper client: used instead of connecting, so a caller that just
+     * connected to learn the helper was up does not connect twice. The driver owns it from here (`close()`
+     * closes it); a restart still reconnects through the socket / spawn path.
+     */
+    client?: SimdClient;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** for `locateHelper` / `$WARDEN_HOME/simd/<version>`; defaults read the process */
+    version?: string;
+    wardenHome?: string;
+    execPath?: string;
+    importDir?: string;
+    exists?: (path: string) => boolean;
+    realpath?: (path: string) => string;
+    /** per-request default in ms, 10 s */
+    defaultTimeoutMs?: number;
+    /** log each helper op and simctl call with its duration (`WARDEN_E2E_DEBUG=1`) */
+    debug?: boolean;
+    /** CoreSimulator devices directory for the host-side `AutomationEnabled` check (default `~/Library/Developer/CoreSimulator/Devices`) */
+    devicesRoot?: string;
+};
+/** USB HID keyboard-page usage ids for the keys `Driver.key` offers. */
+export declare const KEY_USAGE: Readonly<Record<KeyName, number>>;
+export declare function createIosDriver(swap: SwappableClient, simctl: Simctl, opts: {
+    udid: string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    log?: Logger;
+}): IosDriver;
+/**
+ * Open the iOS driver for `udid`. Writes `AutomationEnabled` (best effort) while the helper starts.
+ * `E_HELPER_MISSING` (with the `warden doctor` hint) when no helper binary can be found.
+ */
+export declare function openIosDriver(o: OpenIosDriverOptions): DriverResult<Driver>;

package/types/e2e/src/driver/ios/ios-session.d.ts

@@ -0,0 +1,30 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError, Logger } from "../driver.types";
+import type { SimdClient } from "./simd-client";
+/** The slice of {@link SimdClient} the iOS driver uses; the driver holds this, never a raw client. */
+export type DriverClient = Pick<SimdClient, "request" | "ready" | "close">;
+export type Reopen = () => Promise<Result<SimdClient, DriverError>>;
+export type SwappableClient = {
+    client: DriverClient;
+    /** bumps on every restart, so a caller can tell "someone already restarted it" from "still the stale one" */
+    generation(): number;
+    /**
+     * Replace the helper: ask the current one to `shutdown`, drop it, `reopen()` (socket first, else a
+     * fresh stdio spawn). Single-flight; a caller whose `seenGeneration` is already stale just returns ok.
+     * `crashed`: the helper (or the connection to it) is already gone, so nothing is asked of it; asking
+     * would only make a stdio client respawn a helper to shut it down.
+     */
+    restart(seenGeneration: number, o?: {
+        crashed?: boolean;
+    }): Promise<Result<void, DriverError>>;
+};
+/**
+ * Wraps the helper client so it can be swapped at runtime (bridge-stale recovery) and so every
+ * request's latency can be logged (`debug`, driven by `WARDEN_E2E_DEBUG=1`): `[ios] op snapshot 31 ms`.
+ */
+export declare function swappableClient(initial: SimdClient, o: {
+    now: () => number;
+    log?: Logger;
+    debug?: boolean;
+    reopen?: Reopen;
+}): SwappableClient;

package/types/e2e/src/driver/ios/locate-helper.d.ts

@@ -0,0 +1,38 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError } from "../driver.types";
+import type { OpenIosDriverOptions } from "./ios-driver";
+export declare const HELPER_NAME = "warden-simd";
+export type LocateHelperInput = {
+    /** `WARDEN_SIMD` (a file) and `WARDEN_HELPER_DIR` (a directory holding `warden-simd`) are read from here */
+    env: Readonly<Record<string, string | undefined>>;
+    /** `process.execPath`: a compiled `warden` ships the helper next to itself */
+    execPath: string;
+    /** directory of this module (`packages/e2e/src/driver/ios`), anchors the source-checkout build output */
+    importDir: string;
+    /** `$WARDEN_HOME` (resolved), where `warden doctor` / installs stage `simd/<version>/warden-simd` */
+    wardenHome: string;
+    /** warden version for the staged copy; without it that lookup step is skipped */
+    version?: string;
+    /** file existence, injected */
+    exists: (path: string) => boolean;
+    /** symlink resolution, injected; defaults to identity */
+    realpath?: (path: string) => string;
+};
+export type HelperLocation = {
+    path: string;
+    source: "WARDEN_SIMD" | "WARDEN_HELPER_DIR" | "execPath" | "source-build" | "warden-home";
+};
+export declare const DOCTOR_HINT = "run `warden doctor` to check the iOS driver helper, or set WARDEN_SIMD=/path/to/warden-simd";
+/**
+ * Find the `warden-simd` binary. Order: `WARDEN_SIMD` (file) → `WARDEN_HELPER_DIR/warden-simd` →
+ * next to the real path of the running executable → `<packages/e2e>/native/dist/warden-simd` →
+ * `$WARDEN_HOME/simd/<version>/warden-simd`. An explicitly set env var that points at nothing is an
+ * error, not a fall-through (a stale override should not silently pick another binary).
+ */
+export declare function locateHelper(input: LocateHelperInput): Result<HelperLocation, DriverError>;
+/**
+ * The helper binary: the explicit `helperPath`, else `locateHelper` over the env / install locations. Lives here,
+ * not in `ios-driver.ts`, so a caller that only needs the path (`warden ui` spawning or replacing the helper)
+ * does not load the driver and its protocol schemas.
+ */
+export declare function resolveHelper(o: OpenIosDriverOptions): Result<string, DriverError>;

package/types/e2e/src/driver/ios/normalize.d.ts

@@ -0,0 +1,11 @@
+import type { Element, ScreenInfo, Snapshot } from "../driver.types";
+import type { SnapshotData, WireElement } from "./simd-protocol";
+/** Wire → `Element`: strips `null`s, fills what the helper may omit (`id` as the preorder path, `depth`, `normFrame`, `traits`, `enabled`, `children`). */
+export type Normalized = {
+    elements: Element[];
+    flat: Element[];
+};
+export declare function normalizeElements(wire: readonly WireElement[], screen: ScreenInfo, prefix?: string, depth?: number): Normalized;
+/** One element out of `elementAtPoint` (no siblings, so depth/path are 0). */
+export declare function normalizeElement(wire: WireElement, screen: ScreenInfo): Element;
+export declare function toSnapshot(data: SnapshotData, takenAt: number): Snapshot;

package/types/e2e/src/driver/ios/simctl.d.ts

@@ -0,0 +1,87 @@
+import { type ResetFs } from "../../../../core/src/builds/install";
+import { type Exec, type ExecResult } from "../../../../core/src/exec";
+import type { DriverError, DriverResult, LaunchOptions } from "../driver.types";
+export declare const SIMCTL_CHILD_PREFIX = "SIMCTL_CHILD_";
+/** `xcrun simctl launch [--terminate-running-process] <udid> <bundle> <args…>` (env goes through `SIMCTL_CHILD_*`, see {@link launchEnv}). */
+export declare function launchArgv(udid: string, bundleId: string, opts?: LaunchOptions): string[];
+/** simctl forwards `SIMCTL_CHILD_<NAME>` from its own environment to the launched app as `<NAME>`. */
+export declare function launchEnv(env: Record<string, string> | undefined): Record<string, string>;
+export declare const terminateArgv: (udid: string, bundleId: string) => string[];
+export declare const openUrlArgv: (udid: string, url: string) => string[];
+export declare const installArgv: (udid: string, appPath: string) => string[];
+export declare const uninstallArgv: (udid: string, bundleId: string) => string[];
+/** Exit 0 and a path on stdout when installed; non-zero when not. */
+export declare const appContainerArgv: (udid: string, bundleId: string) => string[];
+/** Lists launchd jobs inside the simulator; a running app shows up as `UIKitApplication:<bundle>[…]` with a PID. */
+export declare const launchctlListArgv: (udid: string) => string[];
+export declare const pbpasteArgv: (udid: string) => string[];
+export declare const appearanceArgv: (udid: string, set?: "light" | "dark") => string[];
+export declare const screenshotArgv: (udid: string, path: string) => string[];
+/** `AutomationEnabled` lets the AX bridge attach without the runner app; written once per open. */
+export declare const automationArgv: (udid: string) => string[];
+/** Where CoreSimulator keeps every simulator's data directory on the host. */
+export declare const defaultDevicesRoot: () => string;
+/**
+ * The simulator's Accessibility preferences, readable from the host without booting anything through `xcrun`
+ * (`simctl spawn` costs 300-500 ms, a `plutil` read about 10 ms).
+ */
+export declare const automationPlistPath: (devicesRoot: string, udid: string) => string;
+/** `plutil -extract AutomationEnabled raw -o - <plist>` prints `true` once the default is written. */
+export declare const automationReadArgv: (plist: string) => string[];
+export type StatusBarOverrides = {
+    time?: string;
+    batteryLevel?: number;
+    batteryState?: "charged" | "charging" | "discharging";
+    wifiBars?: number;
+    cellularBars?: number;
+};
+/** Clean 9:41 status bar by default (stable screenshots); pass `undefined` fields to drop them. */
+export declare function statusBarOverrideArgv(udid: string, o?: StatusBarOverrides): string[];
+export declare const statusBarClearArgv: (udid: string) => string[];
+/**
+ * `simctl pbcopy` reads stdin and `Exec` has none, so the text rides as `$1` of a tiny `sh -c`
+ * (never interpolated into the script): `printf %s "$1" | xcrun simctl pbcopy "$2"`.
+ */
+export declare function pbcopyArgv(udid: string, text: string): string[];
+/** `launchctl list` rows are `PID  STATUS  LABEL`; PID is `-` for loaded-but-not-running jobs. */
+export declare function parseRunning(launchctlOutput: string, bundleId: string): boolean;
+/** Map a failed simctl run to a `DriverError`. `appCommand` marks launch-like calls where "not installed" means the app, not the device. */
+export declare function simctlFailure(argv: readonly string[], res: ExecResult, appCommand?: boolean): DriverError;
+export type SimctlDeps = {
+    udid: string;
+    exec: Exec;
+    /** forwarded to core's installer helpers (resolves `adb`; unused on iOS but part of their deps) */
+    env?: Record<string, string | undefined>;
+    /** app data wipe filesystem; defaults to node fs */
+    resetFs?: ResetFs;
+    /** where the screenshot fallback writes before reading back; defaults to a fresh `os.tmpdir()` dir */
+    scratchDir?: () => Promise<string>;
+    readFile?: (path: string) => Promise<Uint8Array>;
+    rmDir?: (path: string) => Promise<void>;
+    /** CoreSimulator's devices directory, for the host-side `AutomationEnabled` check; defaults to `~/Library/...` */
+    devicesRoot?: string;
+};
+export type Simctl = {
+    launch(bundleId: string, opts?: LaunchOptions): DriverResult<void>;
+    terminate(bundleId: string): DriverResult<void>;
+    openUrl(url: string): DriverResult<void>;
+    install(path: string): DriverResult<void>;
+    uninstall(bundleId: string): DriverResult<void>;
+    isInstalled(bundleId: string): DriverResult<boolean>;
+    isRunning(bundleId: string): DriverResult<boolean>;
+    clearData(bundleId: string, opts?: {
+        keychain?: boolean;
+    }): DriverResult<void>;
+    pbcopy(text: string): DriverResult<void>;
+    pbpaste(): DriverResult<string>;
+    appearance(set?: "light" | "dark"): DriverResult<"light" | "dark">;
+    statusBar(overrides?: StatusBarOverrides | "clear"): DriverResult<void>;
+    /** `simctl io screenshot` to `path`, or (no path) to a scratch file read back as PNG bytes */
+    screenshot(path?: string): DriverResult<{
+        path?: string;
+        png?: Uint8Array;
+    }>;
+    /** `defaults write com.apple.Accessibility AutomationEnabled -bool true` inside the sim */
+    enableAutomation(): DriverResult<void>;
+};
+export declare function createSimctl(deps: SimctlDeps): Simctl;

package/types/e2e/src/driver/ios/simd-client.d.ts

@@ -0,0 +1,68 @@
+import type { Result } from "../../../../types/src/result";
+import type { DriverError, DriverResult, Logger } from "../driver.types";
+import { type LogEvent, type OpData, type ReadyEvent } from "./simd-protocol";
+import { type SimdSpawn, type TransportFactory } from "./simd-transport";
+/**
+ * NDJSON client for `warden-simd`, over the helper's stdio (`spawnSimd`, by-hand runs) or its unix
+ * socket (`connectSimd`, the pre-warmed daemon). Multiplexes requests by id (responses may arrive out
+ * of order), enforces per-op timeouts, forwards `log` events, maps `fatal` to a `DriverError`, and in
+ * stdio mode respawns the helper on the call after a crash.
+ */
+export type SimdEventMap = {
+    ready: ReadyEvent;
+    log: LogEvent;
+    /** the helper reported it cannot continue (also fails every in-flight request) */
+    fatal: DriverError;
+    /** the helper process / connection went away */
+    exit: {
+        exitCode: number | null;
+        expected: boolean;
+    };
+};
+export type RequestOptions = {
+    timeoutMs?: number;
+};
+export type SimdClient = {
+    /** the handshake of the current helper process (refreshed after a respawn) */
+    readonly ready: ReadyEvent;
+    request<Op extends string>(op: Op, params?: Record<string, unknown>, opts?: RequestOptions): DriverResult<OpData<Op>>;
+    /** subscribe; returns the unsubscribe function */
+    on<E extends keyof SimdEventMap>(event: E, handler: (payload: SimdEventMap[E]) => void): () => void;
+    close(): Promise<void>;
+};
+export type ClientOptions = {
+    log?: Logger;
+    /** default per-request timeout, 10 s */
+    defaultTimeoutMs?: number;
+    /** how long to wait for `ready`, 15 s */
+    readyTimeoutMs?: number;
+    /**
+     * respawns allowed in a row after unexpected exits (stdio default 1, socket 0). The budget refills
+     * as soon as the helper answers anything, so each crash gets one respawn but a helper that dies
+     * before answering is not retried forever.
+     */
+    maxRespawns?: number;
+    /** ask the helper to `shutdown` on close (stdio: yes; a shared socket daemon: no) */
+    shutdownOnClose?: boolean;
+};
+/** Shared client engine; the transport decides stdio vs socket. */
+export declare function createSimdClient(factory: TransportFactory, options?: ClientOptions): Promise<Result<SimdClient, DriverError>>;
+export type SpawnSimdOptions = ClientOptions & {
+    helperPath: string;
+    udid: string;
+    /** `--resources <dir>`: where the in-sim AX bridge guest lives */
+    resources?: string;
+    /** extra helper arguments after the standard ones (e.g. `--hid indigo`) */
+    args?: readonly string[];
+    /** injectable process spawn (tests); defaults to `Bun.spawn` */
+    spawn?: SimdSpawn;
+    /** grace period for `close()` before the helper is killed */
+    graceMs?: number;
+};
+/** Stdio mode: own a helper process for this client (by-hand runs). Crashes are retried by one respawn. */
+export declare function spawnSimd(options: SpawnSimdOptions): Promise<Result<SimdClient, DriverError>>;
+export type ConnectSimdOptions = ClientOptions & {
+    socketPath: string;
+};
+/** Socket mode: attach to a running (pre-warmed) helper daemon. `close()` only disconnects; the daemon idles out. */
+export declare function connectSimd(options: ConnectSimdOptions): Promise<Result<SimdClient, DriverError>>;