atp

android-test-pilot

한국어

Automated Android app testing tool. Integrates with Claude Code to automate everything from static source code analysis to real device test execution.

Why This Exists

Testing apps with mobile-mcp means repeating a screenshot → LLM image analysis → next action loop. This approach is:

• Expensive. Every step sends a screenshot image to the LLM, consuming image tokens.
• Slow. Screenshot capture + image transfer + analysis adds latency at every step.

android-test-pilot solves this by using text-based ADB commands as the primary information source.

Conventional approach (mobile-mcp):
  screenshot → LLM image analysis → next action → screenshot → ...
  (image tokens every step, slow)

android-test-pilot:
  dumpsys + logcat text → instant parsing → next action → ...
  (text-based, fast and cheap)
  ↘ falls back to uiautomator → screenshot only when needed

Tier 1 combines dumpsys activity (current Activity), dumpsys window (focused window), and logcat (API responses, View state) to determine app state. All text — minimal token usage and instant parsing.
Screenshots are only used in Tier 3 as a last resort (image rendering verification, unexpected popups).

How It Works

Step 0 — Static Analysis (build app map)
Step 1 — Log Coverage Check & Augmentation
         ↓
         Prerequisites for Step 2

Step 2 — Device Test Execution
         Tier 1: text-based (dumpsys + logcat) → Tier 2: uiautomator → Tier 3: screenshot

Step 0: Static Analysis

Analyzes source code to map the app's structure.

Analysis	Output
Screen navigation flow	navigation_map.mermaid
API connections & response scenarios	api_scenarios.json
View state mapping	view_state_map.json

Step 1: Log Coverage Check & Augmentation

Based on Step 0 results, checks if the source code has the logcat logs needed for testing and adds missing ones.

Log Tag	Purpose	Example
ATP_SCREEN	Screen entry/transition	enter: LoginActivity
ATP_RENDER	View state change	renderState: screen=Login, btnVisible=true
ATP_API	API response	apiResponse: endpoint=GET /api/users, status=200

Step 2: Device Test Execution

Reads a markdown scenario file and runs tests using a 3-tier strategy.

Tier	Tools	When Used	Detectable Info
Tier 1	dumpsys + logcat (text)	Always tried first	Current Activity, focused window, View state, API response data
Tier 2	uiautomator + accessibility tree	When Tier 1 can't determine	Rendered View hierarchy, resource-id, bounds
Tier 3	Screenshot	Last resort	Image rendering, unexpected popup detection

Quickstart (5 minutes)

Goal: run your first scenario against a connected emulator.

# 1. Connect a device or start an emulator
adb devices
# List of devices attached
# emulator-5554   device

# 2. Install the plugin (one-time)
/plugin add panicgit/android-test-pilot
/reload-plugins

# 3. Analyse your app (generates .claude/app-map/*)
/atp:analyze-app

# 4. Add ATP_* logs where coverage is thin
/atp:check-logs

# 5. Write or copy a scenario (use examples/scenarios/quickstart-login.json
#    as a starting point), then run it:
/atp:run-test scenarios/login.json

Expected result table:

Step	Expected	Tier Used	Result
1	LoginActivity foreground	text	PASS
2	Login button enabled	text	PASS
3	HomeActivity opens + auth 200	text	PASS

If a step drops to tier uiautomator or screenshot, see TROUBLESHOOTING.md.

Reference artifacts you can compare your output against live in examples/sample-app-map/ and a ready-to-run scenario in examples/scenarios/quickstart-login.json.

Installation

Requirements

• Node.js >= 18
• ADB (Android SDK Platform-Tools)
• Claude Code
• Android device or emulator (USB debugging enabled)

Plugin Install (Claude Code marketplace)

Install as a Claude Code plugin — MCP server + slash commands all at once:

/plugin

When prompted, add the marketplace: panicgit/android-test-pilot, then:

/reload-plugins

Done. All /atp:* commands and MCP tools are ready.

android-test-pilot is distributed exclusively via the Claude Code marketplace. There is no npm package. For local development on the tool itself, clone the repo and run npm install — the prepare script builds lib/ automatically.

Usage

Run via slash commands in Claude Code.

# 1. Static analysis (Step 0)
/atp:analyze-app

# 2. Log coverage check (Step 1)
/atp:check-logs

# 3. Write a scenario
cp /path/to/android-test-pilot/templates/scenario.md scenarios/login.md
# Edit the scenario...