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
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");
const calls: string[][] = [];
(device as any).mobilecli.executeCommand = function(args: string[]): string {
calls.push(args);
return mockResponse;
};
return { device, calls };
}
test.describe("MobileDevice", () => {
test.describe("coordinate rounding", () => {
test("tap should round fractional coordinates before calling mobilecli", async () => {
const { device, calls } = createMockMobileDevice("");
await device.tap(450, 784.5);
expect(calls.length).toBe(1);
expect(calls[0]).toEqual(["io", "tap", "450,785", "--device", "test-device"]);
});
test("longPress should round fractional coordinates before calling mobilecli", async () => {
const { device, calls } = createMockMobileDevice("");
await device.longPress(100.4, 200.6, 500);
expect(calls.length).toBe(1);
expect(calls[0]).toEqual(["io", "longpress", "100,201", "--duration", "500", "--device", "test-device"]);
});
// mobilecli parses --duration as an integer and rejects "250.5"
test("longPress should round a fractional duration before calling mobilecli", async () => {
const { device, calls } = createMockMobileDevice("");
await device.longPress(100, 200, 250.5);
expect(calls[0]).toEqual(["io", "longpress", "100,200", "--duration", "251", "--device", "test-device"]);
});
test("longPressByRef should round a fractional duration before calling mobilecli", async () => {
const { device, calls } = createMockMobileDevice("");
await device.longPressByRef("@e5", 799.4);
expect(calls[0]).toEqual(["io", "longpress", "@e5", "--duration", "799", "--device", "test-device"]);
});
test("swipeFromCoordinate should round fractional coordinates before calling mobilecli", async () => {
const { device, calls } = createMockMobileDevice("");
await device.swipeFromCoordinate(100.5, 300.2, "up", 400);
expect(calls.length).toBe(1);
expect(calls[0]).toEqual(["io", "swipe", "101,300,101,-100", "--device", "test-device"]);
});
test("tapByRef should pass the element ref to mobilecli io tap", async () => {
const { device, calls } = createMockMobileDevice("");
await device.tapByRef("@e5");
expect(calls[0]).toEqual(["io", "tap", "@e5", "--device", "test-device"]);
});
test("tap should keep integer coordinates unchanged", async () => {
const { device, calls } = createMockMobileDevice("");
await device.tap(450, 785);
expect(calls[0]).toEqual(["io", "tap", "450,785", "--device", "test-device"]);
});
});
test.describe("gestures by element ref", () => {
test("longPressByRef should pass the element ref to mobilecli io longpress", async () => {
const { device, calls } = createMockMobileDevice("");
await device.longPressByRef("@e5", 800);
expect(calls[0]).toEqual(["io", "longpress", "@e5", "--duration", "800", "--device", "test-device"]);
});
test("doubleTapByRef should resolve the ref once and tap the element center twice", async () => {
const dump = { status: "ok", data: { elements: [
{ ref: "@e1", type: "Button", label: "+", rect: { x: 100, y: 200, width: 40, height: 60 } },
] } };
const { device, calls } = createMockMobileDevice(JSON.stringify(dump));
await device.doubleTapByRef("@e1");
expect(calls).toEqual([
["dump", "ui", "--device", "test-device"],
["io", "tap", "120,230", "--device", "test-device"],
["io", "tap", "120,230", "--device", "test-device"],
]);
});
test("doubleTapByRef should raise an actionable error for a ref that is not on screen", async () => {
const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { elements: [] } }));
const pending = device.doubleTapByRef("@e9");
await expect(pending).rejects.toThrow(ActionableError);
await expect(pending).rejects.toThrow(/@e9 was not found on the current screen/);
expect(calls).toEqual([["dump", "ui", "--device", "test-device"]]);
});
});
test.describe("element state", () => {
test("getElementsOnScreen should keep ref, selected, checked and enabled from dump ui", async () => {
const dump = { status: "ok", data: { elements: [{
ref: "e1", type: "Switch", label: "Wi-Fi", rect: { x: 0, y: 0, width: 100, height: 40 },
selected: true, checked: true, enabled: false,
children: [{ ref: "e2", type: "Text", text: "child", rect: { x: 0, y: 0, width: 10, height: 10 } }],
}] } };
const { device } = createMockMobileDevice(JSON.stringify(dump));
const elements = await device.getElementsOnScreen();
expect(elements.map(e => e.ref)).toEqual(["e1", "e2"]);
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", () => {
test("getForegroundApp should call mobilecli apps foreground and fall back to package name when app name is missing", async () => {
const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { packageName: "com.example.app" } }));
const app = await device.getForegroundApp();
expect(calls[0]).toEqual(["apps", "foreground", "--device", "test-device"]);
expect(app).toEqual({ appName: "com.example.app", packageName: "com.example.app" });
});
test("getForegroundApp should include the focused activity reported by mobilecli", async () => {
const { device } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { packageName: "com.android.settings", appName: "Settings", activity: "com.android.settings.SubSettings" } }));
const app = await device.getForegroundApp();
expect(app).toEqual({ appName: "Settings", packageName: "com.android.settings", activity: "com.android.settings.SubSettings" });
});
});
test.describe("fold", () => {
test("fold should call mobilecli device fold with a named posture", async () => {
const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: {} }));
await device.fold("half-open");
expect(calls[0]).toEqual(["device", "fold", "half-open", "--device", "test-device"]);
});
test("fold should call mobilecli device fold with an angle in degrees", async () => {
const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: {} }));
await device.fold(120);
expect(calls[0]).toEqual(["device", "fold", "120", "--device", "test-device"]);
});
});
test.describe("clear app data", () => {
test("clearAppData should call mobilecli apps clear with the package", async () => {
const { device, calls } = createMockMobileDevice("");
await device.clearAppData("com.example.app");
expect(calls[0]).toEqual(["apps", "clear", "com.example.app", "--device", "test-device"]);
});
});
test.describe("location", () => {
test("setLocation should call mobilecli device location set with lat,lng", async () => {
const { device, calls } = createMockMobileDevice("");
await device.setLocation(37.7749, -122.4194);
expect(calls[0]).toEqual(["device", "location", "set", "37.7749,-122.4194", "--device", "test-device"]);
});
test("clearLocation should call mobilecli device location clear", async () => {
const { device, calls } = createMockMobileDevice("");
await device.clearLocation();
expect(calls[0]).toEqual(["device", "location", "clear", "--device", "test-device"]);
});
});
test.describe("clipboard", () => {
test("getClipboard should call mobilecli io clipboard get and return the text", async () => {
const { device, calls } = createMockMobileDevice(JSON.stringify({ status: "ok", data: { text: "hello" } }));
const text = await device.getClipboard();
expect(calls[0]).toEqual(["io", "clipboard", "get", "--device", "test-device"]);
expect(text).toBe("hello");
});
test("setClipboard should call mobilecli io clipboard set with the text", async () => {
const { device, calls } = createMockMobileDevice("");
await device.setClipboard("hello");
expect(calls[0]).toEqual(["io", "clipboard", "set", "hello", "--device", "test-device"]);
});
});
test.describe("logs", () => {
function createMockLogStream(exitCode: number | null): { device: MobileDevice; calls: string[][]; child: any } {
const { device, calls } = createMockMobileDevice("");
const child = new EventEmitter() as any;
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
child.killed = false;
child.kill = () => {
child.killed = true;
child.emit("close", null);
};
(device as any).mobilecli.spawnCommand = function(args: string[]): any {
calls.push(args);
if (exitCode !== null) {
setImmediate(() => child.emit("close", exitCode));
}
return child;
};
return { device, calls, child };
}
test("getLogs should pass limit and each filter as a repeated --filter flag", async () => {
const { device, calls } = createMockLogStream(0);
await device.getLogs(50, ["tag=ActivityManager", "level!=Debug"], 1000);
expect(calls[0]).toEqual(["device", "logs", "--limit", "50", "--filter", "tag=ActivityManager", "--filter", "level!=Debug", "--device", "test-device"]);
});
test("getLogs should return captured output once the stream goes silent for timeoutMs", async () => {
const { device, child } = createMockLogStream(null);
const pending = device.getLogs(50, [], 50);
child.stdout.emit("data", Buffer.from("{\"a\":1}\n"));
expect(await pending).toBe("{\"a\":1}");
expect(child.killed).toBe(true);
});
test("getLogs should reject when mobilecli exits with an error", async () => {
const { device, child } = createMockLogStream(1);
const pending = device.getLogs(5, [], 1000);
child.stderr.emit("data", Buffer.from("no such device"));
await expect(pending).rejects.toThrow("no such device");
});
});
});