Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
fix: raise an actionable error when `dump ui` returns no elements (#457)
yi11136366d5cdd10
diff --git a/src/mobile-device.ts b/src/mobile-device.tsindex 24274f2..55f5215 100644--- a/src/mobile-device.ts+++ b/src/mobile-device.ts@@ -52,8 +52,10 @@ interface UIElementResponse {interface DumpUIResponse {status: "ok",- data: {- elements: UIElementResponse[];+ // mobilecli answers "dump ui" with status "ok" but an empty payload when the+ // device screen is off or locked, so neither level can be relied on.+ data?: {+ elements?: UIElementResponse[];};}@@ -275,7 +277,13 @@ export class MobileDevice implements Robot {public async getElementsOnScreen(): Promise<ScreenElement[]> {const response = this.runJsonCommand<DumpUIResponse>(["dump", "ui"]);- return response.data.elements.flatMap(element => flattenUIElement(element));+ const elements = response.data?.elements;++ if (!elements) {+ throw new ActionableError("No UI hierarchy was returned for this device - its screen is most likely off or locked. Wake it up (for example with mobile_press_button using HOME, or POWER when that is supported) and try again");+ }++ return elements.flatMap(element => flattenUIElement(element));}public async setOrientation(orientation: Orientation): Promise<void> {diff --git a/test/mobile-device.test.ts b/test/mobile-device.test.tsindex 4e454f9..d0232ef 100644--- a/test/mobile-device.test.ts+++ b/test/mobile-device.test.ts@@ -2,6 +2,7 @@ import { test, expect } from "@playwright/test";import { EventEmitter } from "node:events";import { MobileDevice } from "../src/mobile-device";+import { ActionableError } from "../src/robot";function createMockMobileDevice(mockResponse: string): { device: MobileDevice; calls: string[][] } {const device = new MobileDevice("test-device");@@ -73,6 +74,36 @@ test.describe("MobileDevice", () => {expect(elements[0]).toMatchObject({ selected: true, checked: true, enabled: false });expect(elements[1].selected).toBeUndefined();});++ test("getElementsOnScreen should return no elements for an empty hierarchy", async () => {+ const { device } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { elements: [] } }));+ await expect(device.getElementsOnScreen()).resolves.toEqual([]);+ });+ });++ test.describe("empty ui dump", () => {++ // A sleeping or locked device makes mobilecli report success with an+ // empty payload, which used to surface as a raw+ // "Cannot read properties of undefined (reading 'flatMap')" TypeError.+ test("getElementsOnScreen should raise an actionable error when dump ui returns no elements", async () => {+ const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: {} }));+ const pending = device.getElementsOnScreen();++ await expect(pending).rejects.toThrow(ActionableError);+ await expect(pending).rejects.toThrow(/screen is most likely off or locked/);+ expect(calls[0]).toEqual(["dump", "ui", "--device", "test-device"]);+ });++ test("getElementsOnScreen should raise an actionable error when dump ui omits data entirely", async () => {+ const { device } = createMockMobileDevice(JSON.stringify({ status: "ok" }));+ await expect(device.getElementsOnScreen()).rejects.toThrow(/screen is most likely off or locked/);+ });++ test("getElementsOnScreen should raise an actionable error when dump ui data is null", async () => {+ const { device } = createMockMobileDevice(JSON.stringify({ status: "ok", data: null }));+ await expect(device.getElementsOnScreen()).rejects.toThrow(/screen is most likely off or locked/);+ });});test.describe("foreground app", () => {