playwright-for-android

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

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.