import createDebug from 'debug'; import { execFileSync } from 'node:child_process'; import { existsSync, openSync, readSync, closeSync } from 'node:fs'; import { resolve } from 'node:path'; import type { AllocatedDevice, AllocationCriteria, AppInfo, Bounds, ConnectionConfig, DeviceInfo, DeviceSettings, DeviceState, DeviceType, Geolocation, GestureSequence, HardwareButton, LaunchOptions, ListDevicesOptions, MobilewrightSession, DeviceAllocator, Orientation, FoldState, Platform, RecordingOptions, RecordingResult, ScreenSize, ScreenshotOptions, Session, SwipeDirection, SwipeOptions, ViewNode, WebViewBridge, WebViewInfo, WebViewSession, } from '@mobilewright/protocol'; import { NoDeviceAvailableError, gestureSequenceToTapActions, osVersionSatisfies, parseOsVersion } from '@mobilewright/protocol'; import { RpcClient } from './rpc-client.js'; import { resolveMobilecliBinary } from './resolve-binary.js'; import { ensureMobilecliReachable, type ServerHandle } from './server.js'; export const DEFAULT_URL = 'ws://localhost:12000/ws'; export interface MobilecliDriverOptions { /** mobilecli server URL (use for remote servers). Default: ws://localhost:12000/ws */ url?: string; /** Path to the mobilecli binary, if not resolvable via the npm package. */ mobilecliPath?: string; /** Auto-start the mobilecli server if not running (local URLs only). Default: true. */ autoStart?: boolean; } /** * Device IDs whose agent has already been verified in this process. connect() * runs once per test, but the agent doesn't come and go during a run, so the * `mobilecli agent status` subprocess only needs to be spawned once per device. */ const agentVerified = new Set(); // ─── mobilecli RPC response types ───────────────────────────── /** Element shape returned by mobilecli's device.dump.ui JSON response */ interface MobilecliElement { type: string; text?: string; label?: string; name?: string; value?: string; identifier?: string; key?: string; placeholder?: string; rect?: { x: number; y: number; width: number; height: number }; children?: MobilecliElement[]; visible?: boolean; enabled?: boolean; selected?: boolean; checked?: boolean; focused?: boolean; } // The first hide in an app injects an agent, which can be slow. This matches // the write deadline mobilecli gives the method. const HIDE_KEYBOARD_TIMEOUT_MS = 60_000; interface MobilecliKeyboardStatusResponse { visible: boolean; } interface MobilecliAppEntry { packageName?: string; bundleId?: string; appName?: string; version?: string; } interface MobilecliDeviceInfoResponse { device: { platform: string; screenSize?: { width: number; height: number; scale: number; }; }; } interface MobilecliDeviceEntry { id?: string; udid?: string; name: string; platform: string; type: string; state: string; model?: string; version?: string; } interface MobilecliScreenshotResponse { data: string; } interface MobilecliOrientationResponse { orientation: string; } interface MobilecliUIDumpResponse { elements: MobilecliElement[]; } interface MobilecliDevicesResponse { status: string; data: { devices: MobilecliDeviceEntry[]; }; } interface MobilecliAgentStatusResponse { status: string; data: { message?: string; agent?: { version: string; bundleId: string }; }; } /** A single embedded webview as returned by device.webview.list */ interface MobilecliWebViewEntry { id: string; url: string; title: string; bundleId?: string; processName?: string; bounds?: Bounds; isVisible?: boolean; } /** RPC caller bound to a device, used by the webview session. */ type WebViewRpcCall = (method: string, params?: Record) => Promise; const VALID_PLATFORMS = new Set(['ios', 'android']); const VALID_DEVICE_TYPES = new Set(['real', 'simulator', 'emulator']); const VALID_DEVICE_STATES = new Set(['online', 'offline']); function toPlatform(value: string): Platform | undefined { return VALID_PLATFORMS.has(value) ? value as Platform : undefined; } function toDeviceType(value: string): DeviceType { return VALID_DEVICE_TYPES.has(value) ? value as DeviceType : 'real'; } function toDeviceState(value: string): DeviceState { return VALID_DEVICE_STATES.has(value) ? value as DeviceState : 'offline'; } function elementToViewNode(el: MobilecliElement): ViewNode { const bounds = el.rect ?? { x: 0, y: 0, width: 0, height: 0 }; return { type: el.type ?? 'Unknown', label: el.label || undefined, identifier: el.identifier || undefined, key: el.key || undefined, value: el.value || undefined, text: el.text || undefined, placeholder: el.placeholder || undefined, isVisible: typeof el.visible === 'boolean' ? el.visible : bounds.width > 0 && bounds.height > 0, isEnabled: el.enabled ?? true, isSelected: typeof el.selected === 'boolean' ? el.selected : false, isChecked: typeof el.checked === 'boolean' ? el.checked : false, isFocused: typeof el.focused === 'boolean' ? el.focused : false, bounds, children: el.children?.map(elementToViewNode) ?? [], raw: { ...el }, }; } const ZIP_MAGIC = Buffer.from([0x50, 0x4B, 0x03, 0x04]); function assertValidZipFile(path: string): void { if (!existsSync(path)) { throw new Error(`App file not found: ${path}`); } const buf = Buffer.alloc(4); const fd = openSync(path, 'r'); try { readSync(fd, buf, { offset: 0, length: 4, position: 0 }); } finally { closeSync(fd); } if (!buf.equals(ZIP_MAGIC)) { throw new Error(`"${path}" is not a valid ZIP file`); } } const debug = createDebug('mw:driver-mobilecli'); /** * A WebViewSession backed by mobilecli's device.webview.* RPC methods. * Bound to a single webview `id`; the deviceId is injected by the caller. * The core's WebLocator drives the page through evaluate() and the injected * DOM selector engine. */ class MobilecliWebViewSession implements WebViewSession { constructor( private readonly call: WebViewRpcCall, private readonly id: string, ) {} async evaluate(expr: string): Promise { // mobilecli evaluates the expression and returns the value directly // (not wrapped in a { result } envelope). debug('webview.evaluate len=%d prefix=%j', expr.length, expr.slice(0, 100)); const result = await this.call('device.webview.evaluate', { id: this.id, expression: expr, }); if (expr.length < 2000) { debug('webview.evaluate done len=%d result=%j', expr.length, result); } else { debug('webview.evaluate done len=%d', expr.length); } return result; } async goto(url: string): Promise { await this.call('device.webview.goto', { id: this.id, url }); } async goBack(): Promise { await this.call('device.webview.goBack', { id: this.id }); } async goForward(): Promise { await this.call('device.webview.goForward', { id: this.id }); } async reload(): Promise { await this.call('device.webview.reload', { id: this.id }); } async url(): Promise { return this.call('device.webview.url', { id: this.id }); } async title(): Promise { return this.call('device.webview.title', { id: this.id }); } async waitForLoadState(state?: 'load' | 'domcontentloaded'): Promise { await this.call('device.webview.waitForLoadState', { id: this.id, ...(state !== undefined && { state }), }); } async close(): Promise { // mobilecli has no webview-close RPC; webviews are owned by the host app. } } export class MobilecliDriver implements MobilewrightSession, DeviceAllocator { private session: { deviceId: string; deviceName: string; platform: Platform; deviceType: DeviceType; rpc: RpcClient } | null = null; private readonly serverUrl: string; private readonly mobilecliPath?: string; private readonly autoStart: boolean; /** Set only when this instance's own prepare()/connect() call started the server — that's the instance responsible for killing it. */ private ownedServerProcess: ServerHandle | undefined; constructor(opts?: MobilecliDriverOptions) { this.serverUrl = opts?.url ?? DEFAULT_URL; this.mobilecliPath = opts?.mobilecliPath; this.autoStart = opts?.autoStart ?? true; } // ─── Connection ────────────────────────────────────────────── async connect(config: ConnectionConfig): Promise { const url = config.url ?? this.serverUrl; const ensured = await ensureMobilecliReachable(url, { autoStart: this.autoStart, binaryPath: this.mobilecliPath }); // Only this call's own server (if it started one) is ours to track/clean up here — // an undefined serverProcess means the server was already running (e.g. from prepare()), // so any existing handle must be left alone. const startedServerProcess = ensured.serverProcess; if (startedServerProcess) { this.ownedServerProcess = startedServerProcess; } debug('connecting to %s', url); try { const rpc = new RpcClient(url, config.timeout); await rpc.connect(); debug('websocket connected'); const platform = config.platform; let device: DeviceInfo; if (config.deviceId && config.deviceType) { device = { id: config.deviceId, name: '', platform, type: config.deviceType, state: 'online' }; } else if (config.deviceId) { device = await this.findDeviceById(config.deviceId); } else { device = await this.resolveDevice(platform, config.deviceName); } debug('resolved device %s (platform=%s, type=%s)', device.id, platform, device.type); this.ensureAgentInstalled(device); this.session = { deviceId: device.id, deviceName: device.name, platform, deviceType: device.type, rpc }; return { deviceId: device.id, platform }; } catch (err) { if (startedServerProcess) { await startedServerProcess.kill().catch(() => {}); if (this.ownedServerProcess === startedServerProcess) { this.ownedServerProcess = undefined; } } throw err; } } private async findDeviceById(deviceId: string): Promise { const allDevices = await this.listDevices(); const device = allDevices.find((d) => d.id === deviceId); if (!device) { throw new Error(`Device ${deviceId} not found`); } return device; } private async resolveDevice( platform: Platform, deviceName?: RegExp | string, ): Promise { const allDevices = await this.listDevices(); debug('found %d devices, resolving for platform=%s deviceName=%s', allDevices.length, platform, deviceName); const online = allDevices.filter( (d) => d.platform === platform && d.state === 'online', ); let candidates = online.filter( (d) => d.type === 'simulator' || d.type === 'emulator', ); if (candidates.length === 0) { candidates = online; } if (deviceName) { const pattern = typeof deviceName === 'string' ? new RegExp(deviceName) : deviceName; candidates = candidates.filter((d) => pattern.test(d.name)); if (candidates.length === 0) { const available = online.map((d) => `${d.name} (${d.id})`).join(', '); throw new Error( `No online ${platform} device matching ${deviceName} found.\n` + (available ? `Available: ${available}` : `No online ${platform} devices found.`), ); } } if (candidates.length === 0) { throw new Error( `No online ${platform} devices found.\n\n` + (platform === 'ios' ? 'Start a simulator in Xcode, or boot one with:\n xcrun simctl boot ""' : 'Start an emulator in Android Studio, or boot one with:\n emulator -avd '), ); } return candidates[0]; } private ensureAgentInstalled(device: DeviceInfo): void { if (agentVerified.has(device.id)) { debug('agent already verified on %s, skipping status check', device.id); return; } const binary = resolveMobilecliBinary(this.mobilecliPath); debug('running: %s agent status --device %s', binary, device.id); const statusOutput = execFileSync(binary, ['agent', 'status', '--device', device.id], { encoding: 'utf8' }); debug('agent status output: %s', statusOutput.trim()); const statusResponse = JSON.parse(statusOutput) as MobilecliAgentStatusResponse; if (statusResponse.status === 'ok') { agentVerified.add(device.id); return; } if (device.type === 'simulator' || device.type === 'emulator') { debug('agent not installed on %s %s, installing automatically', device.type, device.id); debug('running: %s agent install --device %s --verbose', binary, device.id); const installOutput = execFileSync(binary, ['agent', 'install', '--device', device.id, '--verbose'], { encoding: 'utf8' }); debug('agent install output: %s', installOutput.trim()); const verifyOutput = execFileSync(binary, ['agent', 'status', '--device', device.id], { encoding: 'utf8' }); const verifyResponse = JSON.parse(verifyOutput) as MobilecliAgentStatusResponse; if (verifyResponse.status !== 'ok') { throw new Error(`agent install failed on ${device.type} ${device.id}: ${verifyResponse.data?.message ?? 'unknown error'}`); } agentVerified.add(device.id); return; } throw new Error(`agent not installed, run \`npx mobilewright install --device ${device.id}\` to get started`); } async disconnect(): Promise { await this.requireSession().rpc.disconnect(); this.session = null; if (this.ownedServerProcess) { await this.ownedServerProcess.kill(); this.ownedServerProcess = undefined; } } /** Pre-warm a locally-spawned server before any device-pool workers connect(). No-op for remote URLs already reachable. */ async prepare(): Promise { const ensured = await ensureMobilecliReachable(this.serverUrl, { autoStart: this.autoStart, binaryPath: this.mobilecliPath }); this.ownedServerProcess = ensured.serverProcess; } /** Kill the server started by prepare(), if any. */ async dispose(): Promise { if (this.ownedServerProcess) { await this.ownedServerProcess.kill(); this.ownedServerProcess = undefined; } } // ─── Allocation ──────────────────────────────────────────────── async allocate( criteria: AllocationCriteria, takenDeviceIds: ReadonlySet, ): Promise { if (criteria.osVersion) { // Validate up front: with zero eligible devices the per-device filter below // never parses the expression, and a malformed one would masquerade as a // retriable NoDeviceAvailableError. parseOsVersion(criteria.osVersion); } const devices = await this.listDevices(criteria.platform ? { platform: criteria.platform } : undefined); const namePattern = criteria.deviceNamePattern ? new RegExp(criteria.deviceNamePattern) : undefined; const eligible = devices .filter((d) => d.state === 'online') .filter((d) => !criteria.deviceId || d.id === criteria.deviceId) .filter((d) => !namePattern || namePattern.test(d.name)) .filter((d) => !criteria.deviceType || d.type === criteria.deviceType) .filter((d) => !criteria.osVersion || (d.osVersion !== undefined && osVersionSatisfies(d.osVersion, criteria.osVersion))); if (eligible.length === 0) { // No device can ever satisfy these criteria, so waiting for one to free up // is pointless — a plain Error is not re-queued by the device pool. const available = devices.map((d) => `${d.name} (${d.id}, ${d.state})`).join(', '); throw new Error( `no device matches criteria ${JSON.stringify(criteria)}.\n` + (available ? `Available: ${available}` : 'No devices found.'), ); } const match = eligible.filter((d) => !takenDeviceIds.has(d.id)).at(0); if (!match) { debug('no device matches criteria=%j taken=%j devices=%j', criteria, [...takenDeviceIds], devices.map((d) => ({ id: d.id, name: d.name, state: d.state, type: d.type, osVersion: d.osVersion }))); throw new NoDeviceAvailableError( `no online device available matching criteria ${JSON.stringify(criteria)}`, ); } return { deviceId: match.id, platform: match.platform, driver: 'mobilecli', model: match.model, osVersion: match.osVersion, type: match.type }; } async release(_deviceId: string): Promise { // mobilecli devices are local; nothing to release. } async applyDeviceSettings(settings: DeviceSettings): Promise { await this.call('device.settings.apply', { ...settings }); } // ─── Element Operations ────────────────────────────────────── async getViewHierarchy(): Promise { const result = await this.call('device.dump.ui'); return result.elements.map(elementToViewNode); } async tap(x: number, y: number): Promise { await this.call('device.io.tap', { x: Math.round(x), y: Math.round(y) }); } async doubleTap(x: number, y: number): Promise { const point = { x: Math.round(x), y: Math.round(y) }; await this.call('device.io.tap', point); await this.call('device.io.tap', point); } async longPress(x: number, y: number, duration?: number): Promise { await this.call('device.io.longpress', { x: Math.round(x), y: Math.round(y), ...(duration !== undefined && { duration }), }); } async typeText(text: string): Promise { await this.call('device.io.text', { text }); } async pressKeys(keys: string[]): Promise { await this.call('device.io.keys', { keys }); } async fill(text: string): Promise { // mobilecli sets the text through accessibility on Android, which doesn't race a Compose // TextField moving its cursor after focus; on iOS it presses the HID clear key, then types await this.call('device.io.fill', { text }); } async swipe(direction: SwipeDirection, opts?: SwipeOptions): Promise { const screen = await this.getScreenSize(); const centerX = screen.width / 2; const centerY = screen.height / 2; const startX = opts?.startX ?? centerX; const startY = opts?.startY ?? centerY; const isHorizontal = direction === 'left' || direction === 'right'; const defaultDistance = (isHorizontal ? screen.width : screen.height) * 0.5; const distance = opts?.distance ?? defaultDistance; let endX = startX; let endY = startY; switch (direction) { case 'up': endY = startY - distance; break; case 'down': endY = startY + distance; break; case 'left': endX = startX - distance; break; case 'right': endX = startX + distance; break; } await this.call('device.io.swipe', { x1: Math.round(startX), y1: Math.round(startY), x2: Math.round(endX), y2: Math.round(endY), ...(opts?.duration !== undefined && { duration: opts.duration }), }); } async gesture(gestures: GestureSequence): Promise { await this.call('device.io.gesture', { actions: gestureSequenceToTapActions(gestures) }); } async pressButton(button: HardwareButton): Promise { await this.call('device.io.button', { button }); } async isKeyboardVisible(): Promise { const result = await this.call('device.io.keyboard.status'); return result.visible; } async hideKeyboard(): Promise { await this.call('device.io.keyboard.hide', undefined, HIDE_KEYBOARD_TIMEOUT_MS); } // ─── Screen Operations ─────────────────────────────────────── async screenshot(opts?: ScreenshotOptions): Promise { const result = await this.call('device.screenshot', { ...(opts?.format && { format: opts.format }), ...(opts?.quality !== undefined && { quality: opts.quality }), ...(opts?.scale !== undefined && { scale: opts.scale }), ...(opts?.clip && { clip: opts.clip }), }); let b64 = result.data; const commaIdx = b64.indexOf(','); if (commaIdx !== -1) { b64 = b64.slice(commaIdx + 1); } return Buffer.from(b64, 'base64'); } async getScreenSize(): Promise { const result = await this.call('device.info'); const info = result.device; return info.screenSize ?? { width: 0, height: 0, scale: 1 }; } async getOrientation(): Promise { const result = await this.call('device.io.orientation.get'); return result.orientation === 'landscape' ? 'landscape' : 'portrait'; } async setOrientation(orientation: Orientation): Promise { await this.call('device.io.orientation.set', { orientation }); } async setGeolocation(geolocation: Geolocation | null): Promise { if (geolocation === null) { await this.call('device.location.clear'); return; } await this.call('device.location.set', { latitude: geolocation.latitude, longitude: geolocation.longitude }); } async setFoldState(state: FoldState): Promise { await this.call('device.fold.set', { state: String(state) }); } // ─── Recording Operations ───────────────────────────────────── async startRecording(opts: RecordingOptions): Promise { await this.call('device.screenrecord', { output: opts.output, ...(opts.timeLimit !== undefined && { timeLimit: opts.timeLimit }), }); } async stopRecording(): Promise { return this.call('device.screenrecord.stop'); } // ─── App Operations ────────────────────────────────────────── async launchApp(bundleId: string, opts?: LaunchOptions): Promise { debug('launching %s', bundleId); // iOS/simulator: DeviceKit must be running before the app launches. // A getForegroundApp() call here ensures DeviceKit is up first — // otherwise its startup minimizes the freshly-launched app. if (this.requireSession().platform === 'ios') { try { await this.getForegroundApp(); } catch { // No foreground app yet — fine, we just need DeviceKit running. } } await this.call('device.apps.launch', { bundleId, ...(opts?.locales && { locales: opts.locales }), ...(opts?.activity && { activity: opts.activity }), }); debug('launched %s', bundleId); } async terminateApp(bundleId: string): Promise { debug('terminating %s', bundleId); await this.call('device.apps.terminate', { bundleId }); debug('terminated %s', bundleId); } async clearAppData(bundleId: string): Promise { debug('clearing data of %s', bundleId); await this.call('device.apps.clear', { bundleId }); } async listApps(): Promise { // iOS returns a flat array, Android returns { apps: [...] }. Support both // until the Android mobilecli response is aligned. const result = await this.call('device.apps.list'); const apps = Array.isArray(result) ? result : result.apps; return apps.map((app) => ({ bundleId: app.bundleId ?? app.packageName ?? '', name: app.appName, version: app.version, })); } async getForegroundApp(): Promise { const result = await this.call('device.apps.foreground'); return { bundleId: result.bundleId ?? result.packageName ?? '', name: result.appName, version: result.version, }; } async installApp(path: string): Promise { const session = this.requireSession(); const isSimulator = session.deviceType === 'simulator' || session.deviceType === 'emulator'; if (session.platform === 'ios') { if (isSimulator) { if (!/\.zip$/i.test(path)) { throw new Error( `iOS simulator "${session.deviceName}" requires a .zip of the .app bundle, got: "${path}".\n\n` + 'Build and package it with:\n\n' + ' xcodebuild -scheme -configuration Debug \\\n' + ` -destination "platform=iOS Simulator,name=${session.deviceName}" \\\n` + ' -derivedDataPath build build\n' + ' cd build/Build/Products/Debug-iphonesimulator\n' + ' zip -r MyApp.zip MyApp.app\n\n' + 'Then update your installApps config to point to MyApp.zip.', ); } } else { if (!/\.ipa$/i.test(path)) { throw new Error(`iOS real device requires a .ipa file, got: "${path}".`); } } } else if (session.platform === 'android') { if (!/\.apk$/i.test(path)) { throw new Error(`Android requires a .apk file, got: "${path}".`); } } // The server resolves a relative path against ITS cwd, so send an absolute one. const absolutePath = resolve(path); assertValidZipFile(absolutePath); debug('installing %s', absolutePath); await this.call('device.apps.install', { path: absolutePath }); debug('installed %s', absolutePath); } async uninstallApp(bundleId: string): Promise { // Removing an app that is not installed is not an error: real iOS already // resolves, Android would answer `Failure [DELETE_FAILED_INTERNAL_ERROR]`. const installed = (await this.listApps()).some((app) => app.bundleId === bundleId); if (!installed) { debug('%s is not installed, nothing to uninstall', bundleId); return; } await this.call('device.apps.uninstall', { bundleId }); } // ─── Device Operations ─────────────────────────────────────── async listDevices(opts?: ListDevicesOptions): Promise { const binary = resolveMobilecliBinary(this.mobilecliPath); debug('listing devices'); const output = execFileSync(binary, ['devices'], { encoding: 'utf8' }); const response = JSON.parse(output) as MobilecliDevicesResponse; let devices = response.data.devices; if (opts?.platform) { devices = devices.filter((d) => d.platform === opts.platform); } if (opts?.state) { devices = devices.filter((d) => d.state === opts.state); } const result = devices .filter((d) => toPlatform(d.platform) !== undefined) .map((d) => ({ id: d.id ?? d.udid ?? '', name: d.name, platform: toPlatform(d.platform)!, type: toDeviceType(d.type), state: toDeviceState(d.state), model: d.model, osVersion: d.version, })); debug('found %d device(s)', result.length); return result; } async openUrl(url: string): Promise { await this.call('device.url', { url }); } // ─── WebView ───────────────────────────────────────────────── get webViewBridge(): WebViewBridge { const call: WebViewRpcCall = (method, params) => this.call(method, params); return { listWebViews: async (): Promise => { const entries = await this.call('device.webview.list'); return entries.map((e) => ({ id: e.id, url: e.url, title: e.title, ...(e.bounds && { nativeBounds: e.bounds }), })); }, attachWebView: async (id: string): Promise => { return new MobilecliWebViewSession(call, id); }, }; } // ─── Helpers ───────────────────────────────────────────────── /** RPC call on the active session, auto-injecting deviceId. */ private call(method: string, params?: Record, timeoutMs?: number): Promise { const session = this.requireSession(); return session.rpc.call(method, { deviceId: session.deviceId, ...params }, timeoutMs); } private requireSession() { if (!this.session) throw new Error('No active session. Call connect() first.'); return this.session; } }