playwright-for-android

Drive an Android emulator from your LLM. Build, install, launch, and test a feature end-to-end — get a unified logcat-and-actions timeline back.

---

playwright-for-android is a Model Context Protocol server that turns one structured test task ("verify the login screen rejects an empty password") into one auditable debug run — APK built, AVD booted, app launched, UI driven through adb, logcat captured, screenshots saved, verdict written.

Every UI action lands as a typed MCP tool call, so the entire decision trail is visible in your LLM client's chat history and reproducible from trace.jsonl and logcat.log on disk.

Highlights

• Build → boot → launch → drive → verdict, in one session. Gradle, AVD, install, launch, logcat, and the Marvis UI-tree parser are all orchestrated behind a single start_debug_session call.
• Unified timeline. Every action writes an inline <<< MARVIS_DEV ... >>> marker into the live logcat stream, so cause and effect sit next to each other in timeline.md.
• Auditable by default. Every captured frame, every action, and every UX observation lands under <project_root>/playwright-for-android/<timestamp>/.

Install

As a Claude Code plugin (recommended)

# Inside Claude Code:
/plugin marketplace add /path/to/playwright-for-android
/plugin install playwright-for-android@FCLab.SKKU

The bundled plugin manifest registers the MCP server automatically via ${CLAUDE_PLUGIN_ROOT}/scripts/server.py.

As a standalone MCP server

claude mcp add marvis-dev -- uv run --project /absolute/path/to/playwright-for-android python /absolute/path/to/playwright-for-android/scripts/server.py

Or copy .mcp.json.example to .mcp.json in your project root and edit the path.

Prerequisites

• uv on PATH — manages Python and dependencies automatically (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).
• Android SDK with adb and emulator on PATH (default lookup ~/Library/Android/sdk).
• At least one AVD created via Android Studio's AVD Manager.

uv reads pyproject.toml and installs mcp + pillow into an isolated environment on first launch — no manual pip install step, no global Python pollution.

One-time setup (optional)

python3 scripts/onboard.py

Writes ~/.config/playwright-for-android/config.json with non-secret defaults (SDK path, default AVD).

Tool reference

Tool	Purpose
precheck	JSON readiness report — AVDs, devices, SDK paths
start_debug_session	Build, boot, install, launch; returns first observation
observe_screen	Re-capture the current screen without firing input
tap, long_press, type_text	Touch and keyboard input
scroll_dir, scroll_to_text_tool	Scrolling
press_home, press_back	Hardware-key navigation
wait	Sleep, then re-observe
finish_test	Write report.md + timeline.md, stop logcat, return the report markdown
abort_session	Stop logcat without writing a verdict report

Each action tool returns one text block (task metadata, step counter, UI element list) and one image block (raw screenshot). Coordinates are in image space (half device resolution); the server scales them up before invoking adb input.

See SKILL.md for the full agent-facing contract: workflow, information-trust hierarchy, coordinate conventions, UX-observation rubric, and the report markdown template.

Run artifacts

Each start_debug_session invocation writes one directory under <project_root>/playwright-for-android/<YYYY-MM-DDTHH-MM-SS>/ (override with $PLAYWRIGHT_FOR_ANDROID_RUNS_DIR):

playwright-for-android/2026-05-28T22-15-04/
├── logcat.log              # annotated logcat with inline <<< MARVIS_DEV ... >>> markers
├── trace.jsonl             # one row per step with the action JSON
├── screenshots/
│   ├── step01_raw.jpg
│   └── ...
├── report.md               # verdict supplied to finish_test
├── timeline.md             # report + logcat in one file — the file to read after a run
└── build_error.log         # only if Gradle failed

Add playwright-for-android/ to your project's .gitignore.

Credits

Built by Team Marvis at SungKyunKwan University.

License

MIT — see LICENSE.