@e2e-dev/mobile 0.9.1 → 0.9.2

package/README.md

@@ -1,8 +1,8 @@
 # @e2e-dev/mobile
 
 The mobile engine for [`e2e`](https://www.npmjs.com/package/e2e), built on
-[agent-device](https://github.com/callstack/agent-device): iOS simulators and
-Android emulators through the same `e2e/engine` contract the browser engine
+[agent-device](https://github.com/callstack/agent-device): iOS simulators,
+Android emulators, and connected phones through the same `e2e/engine` contract the browser engine
 implements. A test written against `screen`, `expect`, `app`, and `agent` runs
 on a device target unchanged; nothing in `e2e` core knows this package exists.
 
@@ -18,7 +18,8 @@ npm install --save-dev e2e @e2e-dev/mobile
 ```
 
 `agent-device` needs Xcode with an iOS simulator runtime, or the Android SDK
-with an emulator. Run `npx agent-device doctor` once before handing the target
+with an emulator. A phone needs Developer Mode and runner signing on iOS, or
+USB debugging authorized on Android (see [Physical devices](https://e2e.tester.army/docs/physical-devices)). Run `npx agent-device doctor` once before handing the target
 to the runner.
 
 ```ts title="e2e.config.ts"
@@ -68,7 +69,7 @@ the other old app options are `INVALID_CONFIG` naming their key under `app`.
 | Option | Meaning |
 | --- | --- |
 | `platform` | `'ios'` or `'android'`. |
-| `device` | Simulator or emulator name or UDID. A list is a pool: one worker per entry, worker slot `n` driving the `n`th. Omitted, every booted device of the platform is the pool, as many as the run has slots. |
+| `device` | Simulator or emulator name or UDID, or a connected phone's name. A list is a pool: one worker per entry, worker slot `n` driving the `n`th. Omitted, every booted device of the platform is the pool, as many as the run has slots. |
 | `session` | 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. |
 | `snapshot` | `'full'` (default, includes static text) or `'interactive'` (actionable nodes only). |
 | `settle` | For agent actions: milliseconds the UI must hold still after an action before the agent observes again, default `150`; `false` skips the wait. A test's own steps never settle; `expect` verifies their outcome. |
@@ -145,7 +146,8 @@ test, for upgrade and fresh-install paths the target's `app.appPath` cannot
 express.
 A plain install replaces the binary and keeps its data; `reinstall: true`
 removes the app named by `app` (default: the pinned app) first. It resolves to
-the bundle id or package to `openApp` the build by. `openApp` takes an app id,
+the bundle id or package to `openApp` the build by, else the `app` passed in;
+with no reported id and no `app`, it fails with `ENGINE_FAILURE`. `openApp` takes an app id,
 never a link; `openLink` opens one, under the navigation rule.
 
 ## Agent tools

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.9.1"}
+{"version":"0.9.2"}

package/dist/device.d.ts

@@ -82,8 +82,8 @@ export interface Device {
      * 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`.
+     * one (`INVALID_ARGUMENT` without). `file:`, `data:`, `javascript:`,
+     * `view-source:`, `blob:`, and `filesystem:` links are `POLICY_DENIED`.
      */
     openLink(url: string, options?: {
         app?: string;

package/dist/errors.d.ts

@@ -8,7 +8,7 @@
  * | no active session / session not found / requires a session  | INVALID_STATE                |
  * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
  * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
- * | a ref the daemon no longer knows (action paths only)        | NODE_STALE (retryable)       |
+ * | a stale-ref refusal, by `details.reason` (action paths only) | NODE_STALE (retryable)      |
  * | the iOS runner busy, wedged, or past its watchdog           | ENGINE_FAILURE, naming the   |
  * | a snapshot the iOS runner acquired but could not present    |   runner and the recovery    |
  * | anything else, agent-device's own timeouts included         | ENGINE_FAILURE with the text |
@@ -53,8 +53,10 @@ export declare function isSnapshotPresentationFailure(error: unknown): boolean;
  */
 export declare function runCommand<T>(label: string, work: () => Promise<T>, signal: AbortSignal, where?: string): Promise<T>;
 /**
- * Like translateError, but a ref the daemon no longer binds becomes retryable
- * `NODE_STALE`: nothing was dispatched, so the harness may re-observe and
- * re-resolve the node instead of failing the action.
+ * Like translateError, but a ref agent-device refused as stale becomes
+ * retryable `NODE_STALE`: nothing was dispatched, so the harness may
+ * re-observe and re-resolve the node instead of failing the action. Keyed on
+ * the reason alone: agent-device marks a drag's stale ref `dispatched:
+ * 'unknown'` although it refuses it before the gesture.
  */
 export declare function staleOr(cause: unknown, operation: string, where?: string): Error;

package/dist/errors.js

@@ -8,7 +8,7 @@
  * | no active session / session not found / requires a session  | INVALID_STATE                |
  * | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY      |
  * | "not supported on this device" under any code                | UNSUPPORTED_CAPABILITY       |
- * | a ref the daemon no longer knows (action paths only)        | NODE_STALE (retryable)       |
+ * | a stale-ref refusal, by `details.reason` (action paths only) | NODE_STALE (retryable)      |
  * | the iOS runner busy, wedged, or past its watchdog           | ENGINE_FAILURE, naming the   |
  * | a snapshot the iOS runner acquired but could not present    |   runner and the recovery    |
  * | anything else, agent-device's own timeouts included         | ENGINE_FAILURE with the text |
@@ -61,7 +61,20 @@ const CLI_ADVICE = /--help|command arguments/i;
 const NO_SESSION_PATTERN = /no active (?:app )?session|requires an active session|session\b.*\bnot found|open an app first|no app (?:is )?open/i;
 const UNSUPPORTED_CODES = new Set(['UNSUPPORTED_OPERATION', 'NOT_IMPLEMENTED', 'UNSUPPORTED_PLATFORM']);
 const UNSUPPORTED_PATTERN = /\b(?:is )?not supported\b|\bunsupported\b/i;
-const STALE_PATTERN = /\bref\b.*\b(?:not found|unknown|stale|no longer|expired|invalid|missing)|\b(?:not found|unknown|stale|no longer|expired|invalid|missing)\b.*\bref\b|refs?generation/i;
+/**
+ * The `details.reason` values agent-device refuses an `@ref` with: the ref
+ * names no node of the session's tree, or belongs to a capture the session
+ * has since moved past (a newer snapshot, or an action that expired its refs).
+ * agent-device raises each one while resolving or admitting the ref, before
+ * the action reaches the device.
+ */
+const STALE_REF_REASONS = new Set([
+    'ref_not_found',
+    'ref_frame_expired',
+    'ref_generation_mismatch',
+    'plain_ref_requires_complete_frame',
+    'ref_not_issued',
+]);
 /**
  * What the iOS automation runner reported about itself, by the code
  * agent-device emits for it: `RUNNER_WEDGED` at the top level, `RUNNER_BUSY`
@@ -207,16 +220,18 @@ export async function runCommand(label, work, signal, where) {
     }
 }
 /**
- * Like translateError, but a ref the daemon no longer binds becomes retryable
- * `NODE_STALE`: nothing was dispatched, so the harness may re-observe and
- * re-resolve the node instead of failing the action.
+ * Like translateError, but a ref agent-device refused as stale becomes
+ * retryable `NODE_STALE`: nothing was dispatched, so the harness may
+ * re-observe and re-resolve the node instead of failing the action. Keyed on
+ * the reason alone: agent-device marks a drag's stale ref `dispatched:
+ * 'unknown'` although it refuses it before the gesture.
  */
 export function staleOr(cause, operation, where) {
     if (isClassified(cause))
         return cause;
-    const normalized = normalizeAgentDeviceError(cause);
-    if (STALE_PATTERN.test(normalized.message)) {
-        return new EngineError('NODE_STALE', `${operation}: ${normalized.message}`, { retryable: true, cause });
+    const { reason } = details(cause);
+    if (typeof reason === 'string' && STALE_REF_REASONS.has(reason)) {
+        return new EngineError('NODE_STALE', `${operation}: ${message(cause)}`, { retryable: true, cause });
     }
     return translateError(cause, operation, where);
 }

package/dist/links.d.ts

@@ -5,22 +5,27 @@
  *
  * The runner's own rule (`resolveNavigationUrl`, reached by a fixture as
  * `context.app.resolveUrl`) first demands an app URL, which a device engine
- * never declares, so the same small check lives here rather than behind a
- * gate that would refuse every link.
+ * never declares, and admits http(s) alone, where a device link is any app's
+ * custom scheme. So the check here is a list of refused schemes: the ones
+ * that read local content or inline a document, and the browser wrappers
+ * (`view-source:file:...`, `blob:`, `filesystem:`) that carry one inside.
  */
 /** Whether agent-device would open this string as a URL rather than resolve it as an app. */
 export declare function isLink(value: string): boolean;
 /**
  * Parses a link a test asked to open. A string that is not an absolute URL
- * is `INVALID_ARGUMENT`; a `file:`, `data:`, or `javascript:` link is
- * `POLICY_DENIED`, as it is for `app.open` on the web.
+ * is `INVALID_ARGUMENT`; a `file:`, `data:`, `javascript:`, `view-source:`,
+ * `blob:`, or `filesystem:` link is `POLICY_DENIED`, as it is for `app.open`
+ * on the web. The message never echoes the input: a malformed link can carry
+ * a magic-link token in its query, path, or userinfo, and nothing about a
+ * string that failed to parse says which part is safe to repeat.
  */
 export declare function linkTarget(input: string): URL;
 /**
  * Refuses a link handed to `openApp`, which opens an app by bundle id,
  * package, or display name. agent-device opens any `scheme:rest` string as
- * a URL, so the check runs before the device sees it: a `file:`, `data:`,
- * or `javascript:` link is `POLICY_DENIED` as it is for `openLink`, any
+ * a URL, so the check runs before the device sees it: a link with a
+ * forbidden scheme is `POLICY_DENIED` as it is for `openLink`, any
  * other link is `INVALID_ARGUMENT` pointing at `openLink`. The message
  * never echoes the link, whose query may carry a magic-link token.
  */

package/dist/links.js

@@ -5,11 +5,13 @@
  *
  * The runner's own rule (`resolveNavigationUrl`, reached by a fixture as
  * `context.app.resolveUrl`) first demands an app URL, which a device engine
- * never declares, so the same small check lives here rather than behind a
- * gate that would refuse every link.
+ * never declares, and admits http(s) alone, where a device link is any app's
+ * custom scheme. So the check here is a list of refused schemes: the ones
+ * that read local content or inline a document, and the browser wrappers
+ * (`view-source:file:...`, `blob:`, `filesystem:`) that carry one inside.
  */
 import { ConfigurationError, TestError } from 'e2e/engine';
-const FORBIDDEN_PROTOCOLS = new Set(['file:', 'data:', 'javascript:']);
+const FORBIDDEN_PROTOCOLS = new Set(['file:', 'data:', 'javascript:', 'view-source:', 'blob:', 'filesystem:']);
 /**
  * What agent-device opens as a URL instead of resolving as an app: a
  * `scheme:rest` string with no whitespace. Every string the device would
@@ -28,8 +30,11 @@ function denyForbiddenScheme(protocol) {
 }
 /**
  * Parses a link a test asked to open. A string that is not an absolute URL
- * is `INVALID_ARGUMENT`; a `file:`, `data:`, or `javascript:` link is
- * `POLICY_DENIED`, as it is for `app.open` on the web.
+ * is `INVALID_ARGUMENT`; a `file:`, `data:`, `javascript:`, `view-source:`,
+ * `blob:`, or `filesystem:` link is `POLICY_DENIED`, as it is for `app.open`
+ * on the web. The message never echoes the input: a malformed link can carry
+ * a magic-link token in its query, path, or userinfo, and nothing about a
+ * string that failed to parse says which part is safe to repeat.
  */
 export function linkTarget(input) {
     let url;
@@ -37,7 +42,7 @@ export function linkTarget(input) {
         url = new URL(input);
     }
     catch {
-        throw new TestError('INVALID_ARGUMENT', `openLink needs an absolute URL such as myapp://orders/42 or https://example.com/verify, got "${input}"`);
+        throw new TestError('INVALID_ARGUMENT', 'openLink needs an absolute URL such as myapp://orders/42 or https://example.com/verify');
     }
     denyForbiddenScheme(url.protocol);
     return url;
@@ -45,8 +50,8 @@ export function linkTarget(input) {
 /**
  * Refuses a link handed to `openApp`, which opens an app by bundle id,
  * package, or display name. agent-device opens any `scheme:rest` string as
- * a URL, so the check runs before the device sees it: a `file:`, `data:`,
- * or `javascript:` link is `POLICY_DENIED` as it is for `openLink`, any
+ * a URL, so the check runs before the device sees it: a link with a
+ * forbidden scheme is `POLICY_DENIED` as it is for `openLink`, any
  * other link is `INVALID_ARGUMENT` pointing at `openLink`. The message
  * never echoes the link, whose query may carry a magic-link token.
  */

package/dist/nodes.d.ts

@@ -6,48 +6,14 @@
  * vocabulary `screen.getByRole` and trace relocation speak, and mints the
  * ids the surface owns.
  */
+import type { SnapshotNode } from 'agent-device';
 import type { SemanticNode, ViewportSize } from 'e2e/engine';
-import type { Rect } from './support.ts';
-/** The subset of an agent-device snapshot node this engine reads. */
-export interface RawNode {
-    readonly ref?: string;
-    readonly index?: number;
-    readonly parentIndex?: number;
-    readonly depth?: number;
-    readonly type?: string;
-    readonly role?: string;
-    readonly label?: string;
-    readonly value?: string;
-    /** True while a text field shows its placeholder; the runner then reports the placeholder as the value. */
-    readonly hintShowing?: boolean;
-    /**
-     * Android's content description when it differs from `label`: the
-     * accessible name an app set beside visible text (agent-device 0.21.14+).
-     */
-    readonly contentDescription?: string;
-    /** The field's placeholder text, showing or not (agent-device 0.21.16+). */
-    readonly placeholder?: string;
-    /** The checked state of a checkable control; absent for one that cannot be checked or an older helper. */
-    readonly checked?: boolean;
-    /** The accessibility heading flag an app set on the node (Android). */
-    readonly heading?: boolean;
-    /** The localized role description an app set beside the native class, verbatim (`Tab`, `Tab List`). */
-    readonly roleDescription?: string;
-    readonly identifier?: string;
-    readonly rect?: Rect;
-    readonly enabled?: boolean;
-    readonly selected?: boolean;
-    readonly focused?: boolean;
-    /** Native accessibility facts; absent means unavailable, not false. */
-    readonly editable?: boolean;
-    readonly password?: boolean;
-    readonly visibleToUser?: boolean;
-    readonly hittable?: boolean;
-    readonly appName?: string;
-    readonly windowTitle?: string;
-    /** The package (Android) or bundle id (iOS) of the window the node belongs to, when agent-device reports it. */
-    readonly bundleId?: string;
-}
+/**
+ * One agent-device snapshot node as this engine reads it: agent-device's own
+ * node type, every field optional, since the projection tolerates each one
+ * missing (a fixture, a producer that does not read it).
+ */
+export type RawNode = Readonly<Partial<SnapshotNode>>;
 /** One projected node with what the surface needs to act on it and to answer selector terms. */
 export interface ProjectedNode {
     readonly id: string;

package/dist/options.d.ts

@@ -33,8 +33,9 @@ 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
+     * Device to use: a simulator or emulator by name, simulator UDID, or
+     * emulator serial (`emulator-5554`), or a connected phone by name. 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

package/dist/support.d.ts

@@ -1,4 +1,5 @@
 /** Shared helpers for the agent-device engine: error constructors, filenames, PNG headers, gestures, the screen location and size. */
+import type { CaptureScreenshotResult } from 'agent-device';
 import { EngineError, type Momentum, type ScrollDirection, type ViewportSize } from 'e2e/engine';
 export interface Point {
     readonly x: number;
@@ -46,14 +47,7 @@ export declare function swipeWithin(rect: Rect, direction: ScrollDirection, mome
  */
 export declare function screenLocation(app: string | undefined, title: string | undefined): string | undefined;
 /** The screenshot fields a viewport probe reads off agent-device's response. */
-export interface RawScreenshotResult {
-    readonly path?: string;
-    readonly width?: number;
-    readonly height?: number;
-    readonly logicalWidth?: number;
-    readonly logicalHeight?: number;
-    readonly pixelDensity?: number;
-}
+export type RawScreenshotResult = Partial<Pick<CaptureScreenshotResult, 'path' | 'width' | 'height' | 'logicalWidth' | 'logicalHeight' | 'pixelDensity'>>;
 /**
  * The device's logical screen size as its screenshot reports it, in points:
  * the logical dimensions when given, else the pixel dimensions over the

package/dist/surface.js

@@ -634,11 +634,15 @@ export class AgentDeviceSurface {
         if (options.reinstall === true && app === undefined) {
             throw invalidState("reinstall needs an app: pass `app`, or pin one with the target's app.bundleId or app.appPath");
         }
-        const result = (await this.command(`install ${resolved}`, (client) => options.reinstall === true && app !== undefined
+        const result = await this.command(`install ${resolved}`, (client) => options.reinstall === true && app !== undefined
             ? client.apps.reinstall({ ...selection, app, appPath: resolved })
-            : client.apps.install({ ...selection, ...(app === undefined ? {} : { app }), appPath: resolved }), signal));
+            : client.apps.install({ ...selection, ...(app === undefined ? {} : { app }), appPath: resolved }), signal);
         const identity = result.bundleId ?? result.package ?? result.appId;
-        const installed = { app: identity ?? result.app, ...(identity === undefined ? {} : { bundleId: identity }) };
+        const opensBy = identity ?? app;
+        if (opensBy === undefined) {
+            throw new EngineError('ENGINE_FAILURE', `installed ${resolved}, but agent-device reported no bundle id or package for it, so nothing can open it: name the app with the target's \`app.bundleId\` or installApp's \`app\` option`, { retryable: false });
+        }
+        const installed = { app: opensBy, ...(identity === undefined ? {} : { bundleId: identity }) };
         // The engine's own build, installed: without `app`, this is what `app.open()` launches from here on.
         if (engineBuild)
             this.installedApp = installed.app;
@@ -1133,7 +1137,7 @@ export class AgentDeviceSurface {
     async restart(operation) {
         const app = this.pinnedApp;
         if (app === undefined)
-            throw unsupported(`app.restart needs the target's \`app.bundleId\`, or ${UNINSTALLED_BUILD}`);
+            throw unsupported(`launching the app needs the target's \`app.bundleId\`, or ${UNINSTALLED_BUILD}`);
         await this.openApp(app, { relaunch: true }, operation.signal);
     }
     /** Clears the pinned app's persisted state and relaunches it: the device equivalent of a fresh context. */
@@ -1199,7 +1203,7 @@ export class AgentDeviceSurface {
             const directory = mkdtempSync(path.join(tmpdir(), 'e2e-agent-device-'));
             const file = path.join(directory, 'screenshot.png');
             try {
-                return await read((await client.capture.screenshot({ path: file })), file);
+                return await read(await client.capture.screenshot({ path: file }), file);
             }
             finally {
                 rmSync(directory, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/mobile",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Mobile engine (iOS and Android) for e2e agentic end-to-end testing, built on agent-device",
   "keywords": [
     "e2e",
@@ -51,7 +51,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "agent-device": "0.21.18",
+    "agent-device": "0.21.20",
     "pngjs": "7.0.0",
     "zod": "4.6.1"
   },
@@ -68,7 +68,7 @@
     "@types/node": "26.6.2",
     "@types/pngjs": "6.0.5",
     "ai": "7.0.107",
-    "e2e": "0.16.0",
+    "e2e": "0.17.0",
     "typescript": "7.0.2",
     "vitest": "5.0.1"
   },