testsAndMisc/python_pkg/android_ui/tests/test_mcp_server.py
Krzysztof kuhy Rudnicki a4738c6fdf
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (mypy, mypy) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (pylint, pylint) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (rest, ) (push) Waiting to run
Pre-commit checks / pre-commit (${{ matrix.group }}) (shellcheck, shellcheck) (push) Waiting to run
Python tests / test (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
Shell tests / shell-tests (push) Waiting to run
Shell tests / lib-tests (push) Waiting to run
Shell tests / arch-tests (push) Waiting to run
Add android_ui MCP server and Firebase flow
Expose dump/find/tap/type_into/type_into_field/wait_for/scroll_to/focus
over FastMCP stdio. Every driver failure comes back as isError naming
the query and count; typed text is never echoed. Add the workout_app
Firebase flow script and register the server in .mcp.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 08:45:30 +01:00

245 lines
9.2 KiB
Python

"""Tests for :mod:`python_pkg.android_ui.mcp_server`.
The server runs in-process (FastMCP's in-memory client) over the REAL
:class:`AndroidUi`, wired to the scripted adb stand-in, so every ``isError``
asserted here comes from the driver's own verification -- not from a mock
that was told to fail. No real adb runs.
"""
from __future__ import annotations
import asyncio
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
from unittest.mock import MagicMock, patch
from fastmcp import Client
import pytest
from python_pkg.android_ui import mcp_server
from python_pkg.android_ui.driver import AndroidUi, UiAutomationError
from python_pkg.android_ui.tests.conftest import FakeDevice, node, tree
from python_pkg.phone_guard.vd_state import SessionDisplay
from python_pkg.phone_lease import PhoneBusyError
if TYPE_CHECKING:
from collections.abc import Iterator
from mcp.types import CallToolResult
TARGET = "python_pkg.android_ui._mcp_target"
CLI = "python_pkg.android_ui.cli"
TOOLS = {
"dump",
"find",
"tap",
"type_into",
"type_into_field",
"wait_for",
"scroll_to",
"focus",
}
# Real screen, so FakeDevice's display-0 bookkeeping applies.
REAL = {"display": 0}
FIELD = "android.widget.EditText"
@dataclass
class Rig:
"""The scripted adb plus the lease mock every tool call goes through."""
adb: FakeDevice
acquire: MagicMock
@pytest.fixture
def rig(monkeypatch: pytest.MonkeyPatch) -> Iterator[Rig]:
"""One phone (SER1), no virtual display, a free lease, a fake adb."""
fake = FakeDevice()
def build(serial: str | None = None, display: int | None = None) -> AndroidUi:
ui = AndroidUi(serial=serial, display=display, settle_seconds=0.0)
monkeypatch.setattr(ui, "_run", fake.run)
return ui
with (
patch(f"{TARGET}.resolve_serial", side_effect=lambda s=None: s or "SER1"),
patch(f"{TARGET}.acquire") as acquire,
patch(f"{TARGET}.AndroidUi", side_effect=build),
patch(f"{CLI}.owner_id", return_value="claude:1"),
patch(f"{CLI}.own_display", return_value=None),
patch(f"{CLI}.display_owner", return_value=None),
):
yield Rig(fake, acquire)
def call(name: str, args: dict[str, Any] | None = None) -> CallToolResult:
"""Call one tool through a real MCP client session."""
async def _go() -> CallToolResult:
async with Client(mcp_server.mcp) as client:
return await client.call_tool(name, args or {}, raise_on_error=False)
return asyncio.run(_go())
def error_text(result: CallToolResult) -> str:
"""Return the error message of a failed call, asserting it failed."""
assert result.is_error, f"expected isError, got {result}"
return " ".join(getattr(c, "text", "") for c in result.content)
def _two_backs() -> str:
return tree(
node("Back", bounds="[0,0][100,50]"),
node("OFFLINE BACKUP", bounds="[0,100][100,150]"),
)
class TestToolList:
def test_exactly_the_eight_driver_tools(self) -> None:
async def _go() -> set[str]:
async with Client(mcp_server.mcp) as client:
return {t.name for t in await client.list_tools()}
assert asyncio.run(_go()) == TOOLS
def test_every_tool_takes_serial_and_display(self) -> None:
async def _go() -> list[dict[str, Any]]:
async with Client(mcp_server.mcp) as client:
return [t.inputSchema for t in await client.list_tools()]
for schema in asyncio.run(_go()):
assert {"serial", "display"} <= set(schema["properties"])
class TestHappyPaths:
def test_dump_lists_elements(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("Settings"), node("Home"))]
result = call("dump", REAL)
assert not result.is_error
assert any("Settings" in line for line in result.data)
def test_find_returns_bounds_without_tapping(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("Settings", bounds="[10,20][110,70]"))]
result = call("find", {"query": "Settings", **REAL})
assert result.data["bounds"] == [10, 20, 110, 70]
assert result.data["center"] == [60, 45]
assert rig.adb.taps() == []
def test_tap_taps_the_one_match(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("Connect", bounds="[0,0][100,50]"))]
result = call("tap", {"query": "Connect", **REAL})
assert not result.is_error
assert rig.adb.taps() == [(50, 25)]
def test_exact_disambiguates(self, rig: Rig) -> None:
rig.adb.trees = [_two_backs()]
result = call("tap", {"query": "Back", "exact": True, **REAL})
assert not result.is_error
assert rig.adb.taps() == [(50, 25)]
def test_wait_for_and_scroll_to(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("Connected."))]
assert call("wait_for", {"query": "Connected.", **REAL}).data["label"] == (
"Connected."
)
assert not call("scroll_to", {"query": "Connected.", **REAL}).is_error
def test_focus_names_the_window(self, rig: Rig) -> None:
assert call("focus", REAL).data == "com.example/com.example.Main"
def test_type_into_verified(self, rig: Rig) -> None:
before = node(desc="Email", cls=FIELD)
after = node("a@b.c", desc="Email", cls=FIELD)
rig.adb.trees = [tree(before), tree(before), tree(after)]
result = call("type_into", {"query": "Email", "text": "a@b.c", **REAL})
assert not result.is_error
def test_type_into_field_verified(self, rig: Rig) -> None:
rig.adb.trees = [tree(node(cls=FIELD)), tree(node("a@b.c", cls=FIELD))]
result = call("type_into_field", {"index": 0, "text": "a@b.c", **REAL})
assert not result.is_error
class TestErrorContract:
def test_tap_with_no_match_is_an_error(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("Settings"))]
result = call("tap", {"query": "No Such Button", "timeout": 0.2, **REAL})
message = error_text(result)
assert "No Such Button" in message
assert "Settings" in message # what IS on screen
assert rig.adb.taps() == []
def test_tap_with_two_matches_is_an_error(self, rig: Rig) -> None:
rig.adb.trees = [_two_backs()]
message = error_text(call("tap", {"query": "Back", "timeout": 0.2, **REAL}))
assert "2 elements match 'Back'" in message
assert rig.adb.taps() == []
def test_unchanged_type_into_is_an_error(self, rig: Rig) -> None:
rig.adb.trees = [tree(node("old", desc="Email", cls=FIELD))]
result = call("type_into", {"query": "Email", "text": "hunter2!", **REAL})
message = error_text(result)
assert "'Email'" in message
assert "length 3 before and after" in message
assert "hunter2" not in message
def test_unchanged_type_into_field_is_an_error(self, rig: Rig) -> None:
rig.adb.trees = [tree(node(cls=FIELD))]
result = call("type_into_field", {"index": 0, "text": "hunter2!", **REAL})
message = error_text(result)
assert "field #0" in message
assert "length 0 before and after" in message
assert "hunter2" not in message
def test_adb_failure_while_typing_never_echoes_the_text(
self, rig: Rig, monkeypatch: pytest.MonkeyPatch
) -> None:
rig.adb.trees = [tree(node(cls=FIELD))]
real_run = rig.adb.run
def failing(*args: str, timeout: float = 30.0) -> str:
if "text" in args:
msg = f"adb failed (1): {' '.join(args)}\nerror: hunter2secret"
raise UiAutomationError(msg)
return real_run(*args, timeout=timeout)
monkeypatch.setattr(rig.adb, "run", failing)
result = call("type_into_field", {"index": 0, "text": "hunter2secret", **REAL})
message = error_text(result)
assert "hunter2" not in message
assert "redacted" in message
def test_lease_held_elsewhere_is_an_error(self, rig: Rig) -> None:
rig.acquire.side_effect = PhoneBusyError("held by claude:9")
message = error_text(call("dump", REAL))
assert "held by claude:9" in message
assert rig.adb.calls == []
class TestDisplay:
def test_default_is_self_and_errors_without_a_virtual_display(
self, rig: Rig
) -> None:
message = error_text(call("dump"))
assert "no virtual display" in message
assert rig.adb.calls == [] # nothing created, nothing driven
def test_self_drives_the_sessions_own_display(self, rig: Rig) -> None:
mine = SessionDisplay(owner_dir="d", display=7, sf="sf", package="com.example")
with (
patch(f"{CLI}.own_display", return_value=mine),
patch("python_pkg.android_ui._a11y_helper.dump_display") as dump_vd,
):
dump_vd.return_value = tree(node("Settings"))
result = call("find", {"query": "Settings"})
assert not result.is_error
assert dump_vd.call_args.args[1] == 7
assert rig.acquire.call_args.kwargs["scope"] == "pkg:com.example"
def test_display_zero_is_the_real_screen(self, rig: Rig) -> None:
call("dump", {"display": "0"})
assert rig.acquire.call_args.kwargs["scope"] == "pkg:__screen__"
assert any(c[:2] == ("shell", "uiautomator") for c in rig.adb.calls)