Skip to content

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.

fix: raise an actionable error when `dump ui` returns no elements (#457)

yi11136366d5cdd10
diff --git a/src/mobile-device.ts b/src/mobile-device.ts
index 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.ts
index 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", () => {