e2e 0.15.1 → 0.15.2

package/docs/reference/mobile.mdx

@@ -0,0 +1,522 @@
+---
+title: Mobile
+description: Mobile engine options and the device fixture for iOS and Android.
+---
+
+`@e2e-dev/mobile` drives iOS simulators and Android emulators through
+[agent-device](https://github.com/callstack/agent-device). `agent`, `app`,
+`screen`, and `expect` work as they do everywhere; this page covers what is
+specific to a device target. Import `test` from the package to have `device`
+typed, and declare `requires: ['device']` in a suite that also runs on the
+web.
+
+Choose **Mobile (iOS/Android)** in `e2e init` to add the package with a
+Settings example. iOS needs Xcode and a simulator; Android needs the Android
+SDK and an emulator.
+
+The package includes a compatible version of `agent-device`; no separate
+installation is needed.
+
+## Engine
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+import { mobileTools } from '@e2e-dev/mobile/tools';
+import { gateway } from 'ai';
+
+const iphone = mobile({ platform: 'ios' });
+const pixel = mobile({ platform: 'android' });
+
+export default {
+  targets: [
+    { name: 'iphone', engine: iphone, app: { bundleId: 'Settings' } },
+    { name: 'pixel', engine: pixel, app: { bundleId: 'com.android.settings' } },
+  ],
+  workers: 1,
+  agents: {
+    default: {
+      model: gateway('openai/gpt-6-luna-fast'),
+      tools: mobileTools(iphone, pixel),
+    },
+  },
+} satisfies E2EConfig;
+```
+
+Create an engine for each platform you test. Use `platforms: ['ios']` or
+`platforms: ['android']` on tests with platform-specific labels or operations.
+`app.open()` launches the target's app fresh; an attempt launches nothing
+on its own, so a test starts where the previous one left the app. `app.open`
+takes no path on a device: a link goes through `device.openLink`.
+
+The app under test is the target's `app`, not an engine option: `bundleId`,
+`appPath`, `launchArguments`, `permissions`, `identity`, and `environment`
+are documented under [the app under test](/reference/config#the-app-under-test).
+A device target needs `app.bundleId` or `app.appPath`. An `app.url` (not
+supported yet), a link in `bundleId` (a test opens one with
+`device.openLink`), and an unknown permission name are `INVALID_CONFIG` at
+config load. `mobile({ app })` and the other old app options fail naming
+their key under `app`.
+
+`app.appPath` is the build the suite runs against. The engine installs
+nothing on its own: `device.installApp()` with no path installs it, once per
+device, where the suite says so, and a device provider installs it on the
+device it leases. Without `bundleId`, the installed bundle id or package
+becomes the app `app.open()` launches. Declare an `identity` when the build
+path changes per run (a version in it) so recordings survive the rename.
+
+`mobile()` takes only how the device is driven:
+
+```ts
+/**
+ * Options of the device engine: which devices it drives and how. The app
+ * under test is the target's `app` (`bundleId`, `appPath`,
+ * `launchArguments`, `permissions`). Every optional value also accepts
+ * `undefined`, so values read straight from `process.env` need no
+ * conditional spread.
+ */
+export interface MobileOptions {
+  /** Platform the target's device runs. */
+  readonly platform: MobilePlatform;
+  /**
+   * Simulator or emulator to use, by name, simulator UDID, or emulator
+   * serial (`emulator-5554`). A list is a pool: the
+   * engine declares one worker per entry and worker slot `n` drives the
+   * `n`th, so `workers` at or above the pool size runs the target's files
+   * across every device at once. Omitted, the pool is every booted device of
+   * the platform at `prepare`, as many as the run has slots; with none booted,
+   * agent-device boots one. A `DeviceProvider` leases hosted devices instead:
+   * one per worker slot at `prepare`, each driven through the daemon and
+   * client configuration the lease names, all released when the run ends.
+   */
+  readonly device?: string | readonly string[] | DeviceProvider | undefined;
+  /**
+   * agent-device session name, before the worker slot: slot `n` drives its
+   * device under `<session>-<n>`, `e2e-<target name>-<n>` by default. One run
+   * per session at a time: concurrent runs on the same session interleave
+   * taps.
+   */
+  readonly session?: string | undefined;
+  /**
+   * What an observation captures. `full` (default) includes static text, so
+   * judgments can read values; `interactive` keeps only actionable nodes and
+   * is cheaper on screens with long lists.
+   */
+  readonly snapshot?: 'full' | 'interactive' | undefined;
+  /**
+   * UI stability window after a tap, fill, screen scroll, or back, in
+   * milliseconds. Default 150. Raise it for slow transitions. `0` keeps only
+   * the first re-observation; `false` skips the wait.
+   */
+  readonly settle?: number | false | undefined;
+  /**
+   * Wait before acting on a control that just appeared or moved, in
+   * milliseconds. Default 500. Accessibility bounds cannot tell a sliding
+   * control from a landed one (iOS reports the final frame at once, Android
+   * the frame in flight), so the control is found again in a fresh snapshot
+   * once the wait is over and acted on where it landed. Unmoved controls are
+   * acted on immediately. Raise this for slower transitions.
+   */
+  readonly transition?: number | undefined;
+  /**
+   * Whether video recordings draw agent-device's touch indicator where a
+   * test tapped. Default `true`. `false` records the plain screen and skips
+   * drawing the indicator when the recording stops, which on a hosted daemon
+   * such as EAS Simulators' can outlast `cleanupTimeout`.
+   */
+  readonly videoTouches?: boolean | undefined;
+}
+
+/** A permission's state: held, refused, or not asked for yet, so the OS asks again. */
+export type PermissionState = 'grant' | 'deny' | 'reset';
+
+/** Permissions an app holds when it launches, by name. */
+export type LaunchPermissions = Readonly<Partial<Record<DevicePermission, PermissionState>>>;
+```
+
+An empty `device` list is `INVALID_CONFIG`, and so is an option `mobile()`
+does not take, naming the nearest known option when it is a likely typo and
+every option otherwise. A `device` provider object
+leases hosted devices; see [Hosted devices](/mobile#hosted-devices) for the
+`DeviceProvider` contract and an example provider.
+
+Devices boot in `prepare`, once per run and before the run's clock starts, so
+a cold boot on CI is never charged against `launchTimeout`. agent-device
+commands take no abort signal, so a timed-out command keeps running on the
+device; the next attempt waits for it to settle. On iOS, `prepare` starts the
+automation runner on every device with agent-device's `prepare ios-runner`,
+so its first launch is paid before the first test, then brings the target's
+`app.bundleId` up once per device when it is installed; a build the suite
+installs itself comes up with the first `app.open()`, which relaunches it
+fresh whenever a test asks. A runner that does not start in `prepare` is logged and left
+to the first attempt, and that device's app is not opened there.
+
+`app.launchArguments` and `app.permissions` ride every fresh launch of the
+pinned app: `app.open()`, `app.restart()`, and `app.clearState()`, which
+resets the permissions with the data. iOS hands the arguments to the app
+process (`ProcessInfo.processInfo.arguments`); Android appends them to
+`am start`, so `['--ez', 'e2e', 'true']` is a boolean intent extra. `deny` is
+a recorded refusal on iOS, where the app is told no without a prompt, and a
+revocation on Android, where the OS asks again when the app requests the
+permission. The permissions are set before the app starts,
+since iOS terminates a running app whose permission changed and Android one
+whose permission was revoked. agent-device sets them on the app its session
+is on, and only an open puts a session on an app: the warm-up's open in
+`prepare` does that under the session the worker resumes, so a worker's
+launches set them straight away. A run without `prepare`, the first launch
+after `device.closeApp`, and an app the session has not opened get one
+foreground open first; that open is the one process start no permission can
+precede, and the relaunch after it has them. The warm-up passes no launch
+argument and touches no permission.
+`device.openApp(app, { relaunch: true, launchArguments, permissions })` does
+the same for one launch of any app. A permission name outside
+`DevicePermission` (naming the nearest one when it is a likely typo) or a
+state other than `grant`, `deny`, or `reset` fails before any device command:
+`INVALID_CONFIG` in `app.permissions`, `INVALID_ARGUMENT` in
+`device.openApp`.
+
+The engine declares one worker per configured device. With no `device`,
+`prepare` uses the booted devices it finds, capped by the run's slots, and
+boots one when none are. Two workers never drive the same simulator. To
+split a target's files across devices, pass a pool and set `workers` to at
+least its size.
+
+```ts
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+
+const iphones = mobile({
+  platform: 'ios',
+  device: ['iPhone 17', 'iPhone 17 Pro'],
+});
+
+export default {
+  targets: [{ name: 'ios', engine: iphones, app: { bundleId: 'com.example.app' } }],
+  workers: 2,
+} satisfies E2EConfig;
+```
+
+### Capabilities
+
+| Contract member | On a device |
+| --- | --- |
+| `observe` | The accessibility tree with rects. iOS: `Button` is `button`, `TextField` and `SearchField` are `textbox`, `SecureTextField` is a secure `textbox`, `Cell` is `listitem`, `StaticText` is `text`, `Switch` is `switch` with `checked`, `TabBar` and `SegmentedControl` are `tablist` and the buttons inside them `tab`, `ProgressIndicator` is `progressbar`, `ActivityIndicator` is `status`, `Stepper` is `spinbutton`, `Toolbar`, `Menu`, and `RadioGroup` are `toolbar`, `menu`, and `radiogroup`. Android: `TextView` is `text`, `EditText` is `textbox` and one UIAutomator flags as `password` is a secure `textbox` like `SecureTextField`, `Switch` and `CheckBox` keep their roles and `RadioButton` is `radio`, each with the `checked` state the device reports, layouts are `group`, `RecyclerView` and `AbsListView` (React Native's `FlatList`) are `list`, `TabLayout` and `BottomNavigationView` are `tablist` with their items as `tab`, `ProgressBar` is `progressbar`, `NumberPicker` is `spinbutton`, `Toolbar` and `RadioGroup` keep their names. Any other type is kept verbatim in lower case (`picker-wheel`), so it answers no vocabulary role, unless the platform reports it editable, which makes it a `textbox`. React Native on iOS has no trait for `checkbox`, `radio`, and a few other roles and spells the role and state into the accessibility value instead (`checkbox, unchecked`, `radio button, checked`); such a node takes that role, `checked` and `expanded` from the state words, and reports only what follows them as its value. An iOS field keeps a value equal to its label (an unlabeled field is named by its text); Android's echo of a text view's label as its value is dropped. The accessibility identifier (iOS) or resource id (Android) is the node's `testId`. An Android node is named by the content description its app set (React Native's `accessibilityLabel`), else by its text, and its `text` is what it shows, so a labeled text view or a filled field answers `getByLabel` by its label and `getByText` by its text; a view flagged as a heading is a `heading`, and the role description React Native writes for a role Android has no class for (`Tab`, `Tab List`, `Radio Group`) gives the node that role. A field's hint is its `placeholder` attribute, showing or not. One Android fact is agent-device's, not the platform's: `rect` and every point are the screen's physical pixels; the display density it reports is not applied yet. Android's status bar and navigation bar, the full-width `com.android.systemui` windows along the screen's edges and the narrow status icons (clock, signal, battery) agent-device reports on their own inside that edge band, are left out; the notification shade, system dialogs, and a heads-up notification or other popup inset from the sides stay. Pixels on request, with every secure node's bounds painted black. |
+| `perform` | `tap`, `doubleTap`, `longPress`, `fill`, `clear`, `hover`, `check`, `uncheck`, `press` (`Enter` or one character), `swipe`, `dragTo`, and `focus` on editable fields. A tap on a `switch` or `checkbox` lands on its innermost control, since UIKit reports a settings row as one labelled switch with the real toggle as a child. `check` and `uncheck` need a `checked` state, which Android switches lack and a React Native checkbox or radio on iOS has. `doubleTap` is two presses, 284 to 285 ms apart on iOS (the cadence of agent-device's XCTest tap): agent-device's own double-tap gesture reaches a React Native `Pressable` as one press. A detector with a window of 300 ms or less can read the pair as two single taps. `longPress` holds for one second unless the test passes `duration`, past a React Native `Pressable`'s `delayLongPress` of 500 ms and the longer thresholds apps set; agent-device's own default hold is shorter and registers as a tap on those. `selectOption`, `setInputFiles`, `scrollIntoView`, and `secondaryTap` are not declared, and neither is `tapModifiers`, so `tap` or `doubleTap` with `modifiers` is `UNSUPPORTED_CAPABILITY`. |
+| `performAt` | `tap`, `doubleTap`, `longPress`, and `swipeTo` at a bare screen point, so `screen.tapAt`, `tap({ position })`, `screen.swipe({ from, to })`, and the agent's `tap_at` reach a control the tree does not list. No `hover`, `secondaryTap`, or `dragTo` at a point: touch has none without a node, so `hover_at` needs a listed control. |
+| `keyboard` | `type` and `press` into the focused field, the agent's `type` and `press` without a target and the fallback of `type_at` and `press_at`, and `dismiss`, the agent's `dismiss_keyboard`. |
+| `locate` | Every `screen` query. Text and label queries answer with the innermost match, since a device echoes both up the tree (a React Native input is a host view and the field inside it, both labelled). |
+| `validateApp` | Requires `app.bundleId` or `app.appPath` and refuses `app.url` for now, with a note on reaching this machine from the platform's device. A target with either is a `native-app` target, so `requires: ['native-app']` selects device targets. |
+| `session` | `back`, `restart`, and `reset`. No `open`: `app.open()` takes no path and the runner serves it with `restart`, the fresh launch of the pinned app; the agent's `navigate` verb is unavailable, and `device.openLink(url)` opens a deep link or web link. |
+| `artifacts` | Redacted screenshots under `screenshots/NNN-<label>.png`; a screenshot that cannot be redacted fails instead of being written. Video, when the attempt's [video mode](/reference/config#video) records, as `video/video.mp4`, or a device provider's own recording. No traces. |
+| `location` | `<bundle id> / <screen title>`, the replay cache's anchor. The title is the navigation bar's on iOS and the toolbar's on Android. |
+| `state` | Not declared. `test.setup` and `session:` are unavailable. |
+
+## Replay cache on a device
+
+A step recorded on `com.apple.Preferences / General` replays only when
+Settings is on General again. A mutating project-tool call such as
+`open_app` ends a replay. Declare `app.bundleId` and call `app.open()` first, so steps
+start on the same screen, and switch apps through the `device` fixture
+between steps rather than inside one.
+
+## Device
+
+```ts
+/** Deterministic device management exposed to tests as `device`. */
+export interface Device {
+  /**
+   * A locator from an agent-device selector (`'id=SW_VERSION_SPECIFIER'`,
+   * `'role=StaticText label="26.2"'`), for nodes the closed `screen` query
+   * vocabulary cannot name. Same polling and strictness as any locator.
+   */
+  locator(selector: string): Locator;
+  /** Toggles the device's Wi-Fi. */
+  setNetwork(state: 'online' | 'offline'): Promise<void>;
+  /** Toggles airplane mode. */
+  setAirplaneMode(enabled: boolean): Promise<void>;
+  /**
+   * Grants, denies, or resets one permission for the pinned app, brought to
+   * the foreground first when the session is on no app. A change terminates
+   * a running app on iOS, a revoke one on Android, so it goes before the
+   * `app.open()` a test starts with.
+   */
+  setPermission(permission: DevicePermission, state: PermissionState): Promise<void>;
+  /** Sets the simulated location, switching location services on first on Android. */
+  setLocation(coordinates: { latitude: number; longitude: number }): Promise<void>;
+  /** Turns simulated location off; on Android that is location services off, until the next `setLocation`. */
+  clearLocation(): Promise<void>;
+  /** Sets the system appearance. */
+  setAppearance(mode: 'light' | 'dark'): Promise<void>;
+  /** Rotates the device. */
+  setOrientation(orientation: DeviceOrientation): Promise<void>;
+  /**
+   * Puts a foldable iOS simulator (iPhone Duo) in a hinge pose and resolves
+   * once agent-device reads the angle back from CoreDevice at that pose,
+   * typically 10 to 16 seconds later. `closed` lights the outer display;
+   * `half-open` (a 130° book) and `open` light the inner one, whose app
+   * window has a different size, so the next observation reads a new screen.
+   * Any device without a hinge is `UNSUPPORTED_CAPABILITY`.
+   */
+  fold(pose: FoldPose): Promise<void>;
+  /** Simulates one biometric attempt on the open app. */
+  setBiometrics(sensor: BiometricSensor, result: 'match' | 'nonmatch'): Promise<void>;
+  /** Enrolls or unenrolls the simulator's Face ID or Touch ID. */
+  enrollBiometrics(sensor: 'faceid' | 'touchid', enrolled: boolean): Promise<void>;
+  /**
+   * Installs a build (an iOS `.app` bundle or an Android `.apk`, resolved
+   * against the project root) on the device; without a path, the target's
+   * `app.appPath`. The engine installs nothing on its own, so a suite that runs
+   * against a build calls this once per device, in a fixture or a test.
+   * `reinstall: true` removes the app first so it starts with no data; a
+   * plain install replaces the binary and keeps its data. Resolves to the
+   * identity to `openApp` it by, which becomes the app `app.open()` launches
+   * when the target's build is installed and no `app.bundleId` is pinned.
+   */
+  installApp(appPath?: string, options?: InstallAppOptions): Promise<InstalledApp>;
+  /**
+   * Brings an app to the foreground by bundle id, package, or display name;
+   * `relaunch` restarts it fresh. `launchArguments` and `permissions` apply
+   * to this launch alone; the target's configured ones apply to a `relaunch`
+   * of the pinned app, and to no foreground-only open. A link is
+   * `INVALID_ARGUMENT` (`file:`, `data:`, and `javascript:` are
+   * `POLICY_DENIED`): `openLink` opens one.
+   */
+  openApp(app: string, options?: OpenAppOptions): Promise<void>;
+  /**
+   * Opens a deep link (`myapp://orders/42`) or a web link (`https://...`)
+   * into `app` (default: the pinned app), which the session observes
+   * afterwards. iOS launches the app for a web link and then opens the URL;
+   * a web link the app does not claim goes to Safari, and the next
+   * observation brings the app back. Android starts the link on that
+   * package. Without an app, Android lets the OS route the link; iOS needs
+   * one (`INVALID_ARGUMENT` without). `file:`, `data:`, and `javascript:`
+   * links are `POLICY_DENIED`.
+   */
+  openLink(url: string, options?: { app?: string }): Promise<void>;
+  /**
+   * Terminates the session's app and ends the session, so the next
+   * `openApp` launches it fresh. Until then the screen is unobservable and
+   * `foregroundApp` is `APP_NOT_OPEN`.
+   */
+  closeApp(): Promise<void>;
+  /**
+   * Resets the simulator's keychain, every app's, since simctl has no
+   * per-app reset: what `app.clearState()` leaves behind (a session token, a
+   * Firebase sign-in). iOS simulator only; Android is
+   * `UNSUPPORTED_CAPABILITY`. Launch the app afterwards to see it signed out.
+   */
+  clearKeychain(): Promise<void>;
+  /**
+   * The app the session is on. iOS answers from the session, not the
+   * device, so it names the app the session opened even after `home()`;
+   * Android reads the device's foreground activity. `APP_NOT_OPEN` once
+   * `closeApp` ended the session.
+   */
+  foregroundApp(): Promise<ForegroundApp>;
+  /** Sends the device to its home screen. */
+  home(): Promise<void>;
+  /** Navigates back once (in-app back). */
+  back(): Promise<void>;
+  /** Accepts or dismisses the visible system alert. */
+  alert(action: 'accept' | 'dismiss'): Promise<void>;
+  /**
+   * Dismisses the soft keyboard: the keyboard's own dismiss key where it has
+   * one (Android, iPad), else the way a user does it on an iPhone, a short
+   * drag at the centre of the screen that a scroll view turns into a
+   * dismissal, horizontal first and vertical second, stopping as soon as the
+   * keyboard is gone. The simulator's "Speed up your typing" tip goes through
+   * its Continue button first. A keyboard that outlives both drags fails with
+   * `UNSUPPORTED_CAPABILITY`; the message names the alternatives (the app's
+   * own Done or close control, or pressing Enter on the field).
+   */
+  dismissKeyboard(): Promise<void>;
+  /** Reads the clipboard. */
+  clipboard(): Promise<string>;
+  /** Writes the clipboard. */
+  setClipboard(text: string): Promise<void>;
+}
+
+/** How `device.openApp` launches an app. */
+export interface OpenAppOptions {
+  /** Terminate the app first, so it starts fresh; without it a running app is brought forward as it is. */
+  readonly relaunch?: boolean;
+  /**
+   * Arguments this launch hands the app: its process arguments on iOS,
+   * `am start` arguments on Android. Replaces the target's `app.launchArguments`
+   * for a relaunch of the pinned app.
+   */
+  readonly launchArguments?: readonly string[];
+  /**
+   * Permissions the app holds before this launch, each granted, denied, or
+   * reset. Replaces the target's `app.permissions` for a relaunch of the
+   * pinned app.
+   */
+  readonly permissions?: LaunchPermissions;
+}
+
+/** Permissions agent-device can grant, deny, or reset on an app. */
+export type DevicePermission =
+  | 'camera'
+  | 'microphone'
+  | 'photos'
+  | 'contacts'
+  | 'notifications'
+  | 'calendar'
+  | 'location'
+  | 'reminders'
+  | 'motion'
+  | 'siri'
+  | 'media-library';
+
+/** Orientations `setOrientation` accepts. */
+export type DeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+
+/** Hinge poses `device.fold` accepts: `closed` lights the outer display, `half-open` and `open` the inner one. */
+export type FoldPose = 'closed' | 'half-open' | 'open';
+
+/** How `device.installApp` installs a build. */
+export interface InstallAppOptions {
+  /**
+   * Bundle id or package of the build. `reinstall` needs one: agent-device
+   * removes that app before installing. Defaults to the pinned app.
+   */
+  readonly app?: string;
+  /** Remove the installed app first so the build starts with no data. */
+  readonly reinstall?: boolean;
+}
+
+/** What an install put on the device, as agent-device identified it. */
+export interface InstalledApp {
+  /** The bundle id or package to open the app by. */
+  readonly app: string;
+  readonly bundleId?: string;
+}
+
+/** The app in the foreground, as `foregroundApp` reports it. */
+export interface ForegroundApp {
+  readonly name: string;
+  readonly bundleId?: string;
+}
+
+/** Sensors `setBiometrics` simulates. */
+export type BiometricSensor = 'faceid' | 'touchid' | 'fingerprint';
+```
+
+Every async method is a recorded step named `device.<method>`, bounded by
+`config.actionTimeout`. A lost session is `APP_NOT_OPEN`, that budget
+expiring is `ACTION_FAILED`, a command the platform cannot run is
+`UNSUPPORTED_CAPABILITY`, anything else `ENGINE_FAILURE` with agent-device's
+message: a timeout the device itself reports (a boot, the runner connecting)
+keeps its text and hint there, and a busy or wedged iOS automation runner
+names itself and the recovery (see
+[Troubleshooting](/mobile#troubleshooting)).
+
+`back`, `home`, `alert`, `dismissKeyboard`, `setOrientation`, and `fold`
+change the screen, so they count as actions for the `transition` budget the way a tap
+does: a control that arrives with the screen they reveal waits out the budget
+before the next action lands on it.
+
+`closeApp` terminates the app the session is on and ends the session, so
+`openApp` after it launches the app fresh, on its first screen; a screen
+query or `foregroundApp` in between is `APP_NOT_OPEN`. `foregroundApp` on
+iOS reads the session, not the device: agent-device's `appstate` has no
+device-level answer there, so after `home()` it still names the app the
+session opened. Android reads the device's foreground activity.
+
+`installApp` installs a build from inside a test or a fixture: the run's build once per device (no path installs `app.appPath`), or another build for an upgrade path. A plain
+install keeps the app's data; `reinstall: true` removes the app named by
+`app` (default: the pinned app) first. It resolves to the id to `openApp`
+the build by.
+
+```ts
+const { app } = await device.installApp('./build/MyApp.app', { reinstall: true });
+await device.openApp(app);
+```
+
+`clearKeychain` resets the simulator's keychain, which `app.clearState()`
+leaves alone: simctl resets the whole simulator's, so every app on it loses
+its keychain-backed credentials. iOS only; on Android it is
+`UNSUPPORTED_CAPABILITY` before any device command. Launch the app afterwards
+to see it signed out.
+
+`openApp` brings an app to the foreground by bundle id, package, or display
+name (`Settings`); `relaunch: true` restarts it fresh, and `launchArguments`
+and `permissions` apply to that launch alone (the target's own apply to a
+`relaunch` of the pinned app). It takes no link:
+agent-device opens any `scheme:rest` string as a URL, so a link is refused
+before the device sees it. A `file:`, `data:`, or `javascript:` link is
+`POLICY_DENIED`, the rule every navigation follows; any other link is
+`INVALID_ARGUMENT` pointing at `openLink`.
+
+`openLink` opens a deep link or a web link into `app` (default: the pinned
+app), for magic-link sign-in and deep-link routes, and the session observes
+that app afterwards. iOS launches the app for a web link and then opens the
+URL; a web link the app does not claim goes to Safari, and the next
+observation brings the app back. Android starts the link on that package.
+Without an app, Android lets the OS route the link, to a verified app link
+owner or the browser, and the session follows the package that took it. iOS
+needs an app: an open bound to none leaves no app session to observe, so it
+is `INVALID_ARGUMENT`. `file:`, `data:`, and `javascript:` links are
+`POLICY_DENIED`, as on the web. The report shows the link cut before its
+query and fragment, where a magic link carries its token. The replay cache
+anchors on the location the link lands on: a step recorded after `openLink`
+replays when the link lands on the same screen again.
+
+```ts
+await device.openLink('myapp://orders/42');
+await expect(screen.getByText('Order #42')).toBeVisible();
+```
+
+Use `device.locator` for platform-specific selectors that `screen` queries
+cannot express.
+
+```ts
+await expect(device.locator('role=NavigationBar id=About')).toBeVisible();
+await expect(device.locator('role=StaticText label="iOS Version"')).toHaveText('iOS Version');
+await device.locator('id=SW_VERSION_SPECIFIER role=Button').tap();
+```
+
+Selector terms are agent-device's: `id`, `role`, `text`, `label`, `value`,
+`appname`, `windowtitle`, and the flags `visible`, `hidden`, `editable`,
+`selected`, `focused`, `enabled`, `hittable`. `role` accepts the platform
+type (`StaticText`) or the contract role (`text`).
+
+## Agent tools
+
+`mobileTools(...engines)` adds device tools to an agent's `tools`. It takes at
+least one engine; pass all device engines in one call, and the tools use the
+current attempt's engine.
+
+| Tool | Replay | Purpose |
+| --- | --- | --- |
+| `open_app` | gap | Bring an app to the foreground by id, optionally relaunched. A link is refused, as it is for `device.openApp`. |
+| `swipe` | gap | Free-form swipe between two points in logical pixels. |
+| `alert` | gap | Accept or dismiss a system alert; prefer a listed button, whose tap replays. |
+
+The grammar verbs need no tool pack: the engine's declared actions give the
+agent `tap`, `double_tap`, `long_press`, `hover`, `type`, `press`, `check`,
+`scroll`, `drag`, `scroll_to` by `text` (paging the list until a row reading it
+is drawn), `back`, and `dismiss_keyboard`; there is no `right_click`,
+`select`, `scroll_to` by node id, `upload`, or `navigate` on a device. The
+pixel tools are `screenshot`, `tap_at`, `hover_at` (on a listed control only),
+`type_at`, and `press_at`; `select_at` is not offered. Point actions can tap
+controls absent from the accessibility tree. `type_secret` is offered when
+the step declares a secret.
+
+After a secret fill the agent offers neither `screenshot` nor `tap_at`,
+including in later members of the same serial group. Pixels whose masking the
+engine cannot prove are withheld as `MASKING_UNPROVEN`.
+
+An accessibility capture failure still stops the observation. Device
+screenshot masks depend on secure-field bounds from that capture, so the
+engine cannot prove a fallback screenshot safe when those bounds are missing.
+
+## Exported types
+
+`MobileOptions`, `MobilePlatform`, `DevicePermission`, `LaunchPermissions`,
+`PermissionState`, `DeviceClientConfig`, `DeviceConnection`, `DeviceDaemon`,
+`DeviceProvider`, `DeviceLease`, `DeviceReleaseContext`, `DeviceRequest`,
+`Device`, `DeviceOrientation`, `BiometricSensor`, `ForegroundApp`,
+`InstallAppOptions`, `InstalledApp`, and `OpenAppOptions` are exported from
+`@e2e-dev/mobile`. The runtime exports are `mobile` and `test`, typed with the
+`device` fixture; `mobileTools` comes from `@e2e-dev/mobile/tools`.