@e2e-dev/mobile

The mobile engine for e2e, built on 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.

Install

Run npx e2e init and choose Mobile (iOS/Android) for a Settings example with optional AI testing. Init defaults to iOS on macOS and Android elsewhere; change the platform in e2e.config.ts when needed. Or add the packages to an existing project:

npm install --save-dev e2e @e2e-dev/mobile

agent-device needs Xcode with an iOS simulator runtime, or the Android SDK with an emulator. A phone needs Developer Mode and runner signing on iOS, or USB debugging authorized on Android (see Physical devices). Run npx e2e doctor to check the setup before a run.

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;

A test written against agent, app, screen, and device runs on both targets unchanged. Only a check that names a platform label (General on iOS, Network & internet on Android) needs platforms: ['ios'] or platforms: ['android'] on the test.

The app under test is the target's app; the engine only drives it. A device target needs bundleId or appPath:

app.url is not supported on a device target yet, and mobile({ app }) and the other old app options are INVALID_CONFIG naming their key under app.

mobile() options:

Every optional mobile() value also accepts undefined, so a config passes device: process.env.E2E_DEVICE straight through, with no conditional spread.

What the engine declares

• Observation: the accessibility tree, projected onto the role vocabulary (iOS Button becomes button, TextField becomes textbox, Cell becomes listitem; Android android.widget.TextView becomes text, EditText becomes textbox, Switch becomes switch), with rects, a viewport, and pixels on request with every secure field painted over. Element identifiers (ABOUT, android:id/title) are the node's testId, what getByTestId matches.
• Actions: tap, double tap, long press, fill, clear, check/uncheck (when the tree exposes the checked state, as switches do on both platforms), focus on editable fields, Enter, single-character keys, swipe within a node, drag. selectOption, setInputFiles, scrollIntoView, secondaryTap, modifiers on tap or doubleTap, focus on a control, and other keys fail with UNSUPPORTED_CAPABILITY.
• Location: every screen query, plus agent-device selectors through device.locator('role=navigation-bar id=General').
• Viewport swipe, app.back(), app.restart(), app.clearState(), and redacted screenshots under the attempt artifact directory: the bounds of every secure field are painted black before the file is kept, and a screenshot that cannot be redacted is not written. No state capability: a simulator has no portable session snapshot.
• App kind: a target with app.bundleId or app.appPath is a native-app target, so a portable suite can requires: ['native-app'].

Replay cache

The runner caches agent.act steps by their location anchor, and a device has no address bar. This engine reports one anyway: <bundle id> / <screen title>, with the title read off the navigation bar on iOS and the collapsing toolbar on Android. The app identity is part of the location, so two apps with a "General" screen never share an anchor. A step recorded on com.apple.Preferences / General replays only when that app is on that screen again, and a flow that stays within tap, type, and scroll replays with zero model calls. Declare app.bundleId and call app.open() first, so steps start on the same screen, and prefer the grammar over the open_app tool inside a step: a tool call is a replay gap.

The device fixture

Deterministic device management, recorded as device.<method> steps. Import test from this package to have it typed.

import { test } from '@e2e-dev/mobile';
import { expect } from 'e2e';

test('shows the version in dark mode', async ({ agent, device, screen }) => {
  await device.setAppearance('dark');
  await agent.act('go to General, then About');
  await expect(screen.getByRole('button', /^iOS Version/)).toBeVisible();
  await expect(device.locator('role=navigation-bar id=About')).toBeVisible();
});

Methods: setNetwork, setAirplaneMode, setPermission, setLocation, clearLocation, setAppearance, setOrientation, fold, setBiometrics, enrollBiometrics, installApp, openApp, openLink, closeApp, clearKeychain, foregroundApp, home, back, alert, dismissKeyboard, clipboard, setClipboard, and the locator accessor.

device.unstable_raw is the raw driver session, for what the methods do not cover. Its client calls are not steps: the report and trace leave them out, the cache does not replay them, their arguments reach the driver unredacted, and nothing waits for the screen to settle. Reading it after the worker disposes the session throws INVALID_STATE. It can change in any release (reference).

setNetwork('offline') and setAirplaneMode(true) are Android only. An iOS simulator shares the Mac's network, and simctl can only change its status bar, so on iOS both fail with UNSUPPORTED_CAPABILITY; going back online does nothing there, so a shared cleanup hook passes. On Android, setNetwork('offline') turns off Wi-Fi alone, so the app can stay online over cellular; setAirplaneMode(true) (Android 11 or later) takes it offline.

installApp(appPath, { app, reinstall }) puts a build on the device from a 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, 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

@e2e-dev/mobile/tools exports mobileTools(...engines): open_app, swipe (free-form, in logical pixels), and alert (accept or dismiss a system alert). It takes at least one engine. Pass every device engine the config declares: tool names are fixed, so two packs cannot be merged, and the pack dispatches each call to the engine whose attempt is running. Tools are scoped to the platforms of those engines, so a suite that mixes web and device targets can hand the pack to one agents entry's tools.

Custom tools with a raw driver session

unstable_deviceSession(...engines) from @e2e-dev/mobile/tools gives a custom tool the running attempt's raw driver session, for capabilities e2e does not wrap yet. Its client is bound to the engine's daemon, lease, and session. The client is typed as DeviceSessionClient, exported from @e2e-dev/mobile. This API can change in any release, like device.unstable_raw (reference).

Secrets

type_secret and screen.getByLabel(...).fill(secret) fill declared secrets on a device: a credential's password into a secure field, a secrets entry into any editable input. The model never sees the value, and screenshots are withheld for the rest of the attempt.

Documentation

Full documentation lives at e2e.com/docs.