Skip to content

Android Device QA Setup

Salman Ashraf edited this page Oct 9, 2026 · 2 revisions

Android Device QA Setup

Prepare an Android project for the /mobile-mcp-qa skill with repeatable environment checks, MCP configuration, and a project-level test definition.

This setup layer verifies prerequisites and records the intended QA flow. Device-flow execution is tracked separately in issue #54.

Prerequisites

  • Node.js 18 or newer
  • Android Studio with Android SDK Platform-Tools
  • Android Emulator plus at least one AVD, or an authorized physical device
  • Claude Code, Cursor, Windsurf, or Codex

1. Check the Android Environment

Run from the mobile app project:

npx mobile-ai-agents doctor --platform android

The doctor checks:

  • ANDROID_HOME, ANDROID_SDK_ROOT, and common SDK locations
  • adb availability and version
  • connected and authorized devices
  • Android Emulator installation and configured AVDs
  • Mobile MCP configuration for supported AI clients
  • .mobile-ai-agents/android-device.json validity and APK availability

Use machine-readable output in CI or scripts:

npx mobile-ai-agents doctor --platform android --json

Exit code 1 means at least one required check failed. Warnings identify optional or not-yet-ready items, such as a missing APK before the first build.

2. Configure Mobile MCP

Choose the client you use:

npx mobile-ai-agents mcp setup --client claude
npx mobile-ai-agents mcp setup --client cursor
npx mobile-ai-agents mcp setup --client windsurf
npx mobile-ai-agents mcp setup --client codex

The command adds this server without deleting existing settings or MCP servers:

{
  "command": "npx",
  "args": ["-y", "@mobilenext/mobile-mcp@latest"]
}

Running the same setup command again is safe and leaves an already-correct file unchanged.

Default configuration files:

Client File
Claude Code <project>/.mcp.json
Cursor <project>/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
Codex ~/.codex/config.toml

Use --config <path> to target a different client config file.

3. Define the Project QA Flow

Create .mobile-ai-agents/android-device.json:

npx mobile-ai-agents mcp config init \
  --app-id com.example.app \
  --apk app/build/outputs/apk/debug/app-debug.apk \
  --device auto \
  --flow "Launch app|Open settings|Enable notifications|Restart app"

Generated shape:

{
  "version": 1,
  "platform": "android",
  "appId": "com.example.app",
  "apkPath": "app/build/outputs/apk/debug/app-debug.apk",
  "device": "auto",
  "flow": [
    "Launch app",
    "Open settings",
    "Enable notifications",
    "Restart app"
  ],
  "timeouts": {
    "bootMs": 120000,
    "actionMs": 15000
  },
  "evidenceDir": ".mobile-ai-agents/evidence"
}

You can also copy the configuration template.

Validate after editing:

npx mobile-ai-agents mcp config validate
npx mobile-ai-agents mcp config validate --json

4. Run the Skill

After the doctor has no failures, restart the AI client so it loads Mobile MCP, then invoke:

/mobile-mcp-qa

The skill uses the app ID, build, target device, expected flow, and evidence requirements to guide device QA. See Mobile MCP Integration for the full prompt format and report output.

Troubleshooting

Result Fix
Android SDK not found Install the SDK and set ANDROID_HOME or ANDROID_SDK_ROOT.
adb not found Install Platform-Tools and add <sdk>/platform-tools to PATH.
No ready device Start an AVD or connect a device, enable USB debugging, and authorize the computer.
No AVD configured Create one in Android Studio Device Manager.
MCP not configured Run mcp setup --client <client>, then restart the client.
Invalid project config Run mcp config validate and correct every listed field.
APK missing Build the configured APK before device QA.

Do not use production accounts or irreversible actions during automated QA. Prefer test builds, sandbox credentials, and disposable data.

Clone this wiki locally