📱 Appium MCP (Mobile Automation)
Priority: P1 (HIGH)
[!IMPORTANT]
Tier 0 (Infrastructure): Session creation, device farm connectivity, basic OS interactions.
Tier 1 (Core Gestures): Taps, swipes, text input for native mobile elements.
Tier 2 (Flutter/Single-Canvas): Visual-first automation via screenshot + coordinate taps.
🔌 Activation
Triggers: appium, appium-mcp, appium doctor, mobile verify, android verify, ios verify, lambdatest, real device cloud, flutter widget tap.
🪜 Driver Ladder
sh scripts/preflight.sh — prints MODE: local | local,remote | remote | none; exit 0 usable, 2 not.- Local:
select_device (Android) or prepare_ios_simulator (iOS), embedded drivers. Needs Node 22+, JDK 8+ / Xcode.
- Cloud:
remoteServerUrl (LambdaTest/BrowserStack). URL must match REMOTE_SERVER_URL_ALLOW_REGEX.
- Neither: ask for exported screenshots or cloud video link; label
human-provided.
- Nothing exported: return
BLOCKED (driver: appium), continue other lanes.
NO_UI=true default; AI_VISION_ENABLED=true only for Flutter/canvas. Local single-user or trusted CI only. generate_locators / appium_generate_tests feed test-loop step 4. Full table: driver-ladder.
🛠 Core Workflow (Goal-Oriented)
| Step |
Tool |
Purpose |
| 0 |
select_device / prepare_ios_simulator |
Pick target per ladder rung; cloud skips this. |
| 1 |
appium_session_management (create) |
Open session. Resiliency: Retry with noReset: true on failure. |
| 2 |
appium_get_window_size |
Scale coordinates for high-density displays. |
| 3 |
appium_screenshot |
Capture visual state for Semantic Reasoning. |
| 4 |
appium_gesture / appium_set_value |
Interact. Self-Healing: Re-scan hierarchy if UUID stale. |
| 5 |
appium_session_management (delete) |
MANDATORY Cleanup. |
💡 AI-Driven Methodologies
- Semantic Intent: Find element in hierarchy (e.g., "Login button") instead of raw coordinates. Resilient to layout shifts.
- Dynamic Handling: Unexpected pop-up appears? Pause, reason about alert, dismiss, resume.
- Visual Anchors: Find stable "Anchor" (e.g., Header) and derive coordinates relative to it.
🚫 Anti-Patterns (Zero-Tolerance)
- Hardcoded XPaths: Use
accessibility id or uiautomator. XPath flaky.
- Implicit Wait-Only: Never assume page loaded. Poll for "Source of Truth" element.
- Ignoring QoS: Audit CPU/Memory via
appium_mobile_performance_data. Prevent lag/crashes.
- Orphaned Sessions: Teardown mandatory. Call
delete in cleanup block.
📁 Evidence
.appium-mcp/<session>/: <AC|step>-<before|after>.png (nav shots at maxWidth budget, verdict full-res), <label>.source.xml from appium_get_page_source, perf.json, video.url. Walkthrough records driver: + evidence_dir:.
✅ Evaluation Criteria
- Cleanup Rate: 100% session closure.
- Visual Accuracy: Coordinate-based taps land within 5% of target center.
- Security: No secrets in tool arguments or logs.
🔗 References
- Visual Testing: common-mobile-visual-testing — Methodology for what to verify.
- Driver Ladder: driver-ladder — prerequisites per rung, server env, canonical tools.
- Setup: setup — install, MCP registration snippet, security, alternatives not adopted.
- LambdaTest Setup: lambdatest-cloud-setup — RDC configuration.
- Tool Cheatsheet: tool-cheatsheet — Fast copy-paste args.
- Project Context: project-context — Project-specific overlays/macros.
1---2name: quality-engineering-appium-mcp-23description: Drives iOS/Android mobile devices via Appium MCP. Runs a preflight, picks local emulator/simulator/USB or a device cloud, captures screenshots/page source into a named evidence dir. Use for verifying mobile bugs, E2E tests, and navigating real device clouds (LambdaTest/BrowserStack).4---56# 📱 Appium MCP (Mobile Automation)78## **Priority: P1 (HIGH)**910> [!IMPORTANT]11> **Tier 0 (Infrastructure)**: Session creation, device farm connectivity, basic OS interactions.12> **Tier 1 (Core Gestures)**: Taps, swipes, text input for native mobile elements.13> **Tier 2 (Flutter/Single-Canvas)**: Visual-first automation via screenshot + coordinate taps.1415## 🔌 Activation1617**Triggers**: `appium`, `appium-mcp`, `appium doctor`, `mobile verify`, `android verify`, `ios verify`, `lambdatest`, `real device cloud`, `flutter widget tap`.1819## 🪜 Driver Ladder20211. `sh scripts/preflight.sh` — prints `MODE: local | local,remote | remote | none`; exit 0 usable, 2 not.222. Local: `select_device` (Android) or `prepare_ios_simulator` (iOS), embedded drivers. Needs Node 22+, JDK 8+ / Xcode.233. Cloud: `remoteServerUrl` (LambdaTest/BrowserStack). URL must match `REMOTE_SERVER_URL_ALLOW_REGEX`.244. Neither: ask for exported screenshots or cloud video link; label `human-provided`.255. Nothing exported: return `BLOCKED (driver: appium)`, continue other lanes.2627`NO_UI=true` default; `AI_VISION_ENABLED=true` only for Flutter/canvas. Local single-user or trusted CI only. `generate_locators` / `appium_generate_tests` feed `test-loop` step 4. Full table: [driver-ladder](references/driver-ladder.md).2829## 🛠 Core Workflow (Goal-Oriented)3031| Step | Tool | Purpose |32| :--- | :--- | :--- |33| 0 | `select_device` / `prepare_ios_simulator` | Pick target per ladder rung; cloud skips this. |34| 1 | `appium_session_management` (`create`) | Open session. **Resiliency**: Retry with `noReset: true` on failure. |35| 2 | `appium_get_window_size` | Scale coordinates for high-density displays. |36| 3 | `appium_screenshot` | Capture visual state for **Semantic Reasoning**. |37| 4 | `appium_gesture` / `appium_set_value` | Interact. **Self-Healing**: Re-scan hierarchy if UUID stale. |38| 5 | `appium_session_management` (`delete`) | **MANDATORY Cleanup**. |3940## 💡 AI-Driven Methodologies41- **Semantic Intent**: Find element in hierarchy (e.g., "Login button") instead of raw coordinates. Resilient to layout shifts.42- **Dynamic Handling**: Unexpected pop-up appears? Pause, reason about alert, dismiss, resume.43- **Visual Anchors**: Find stable "Anchor" (e.g., Header) and derive coordinates relative to it.4445## 🚫 Anti-Patterns (Zero-Tolerance)4647- **Hardcoded XPaths**: Use `accessibility id` or `uiautomator`. XPath flaky.48- **Implicit Wait-Only**: Never assume page loaded. Poll for "Source of Truth" element.49- **Ignoring QoS**: Audit CPU/Memory via `appium_mobile_performance_data`. Prevent lag/crashes.50- **Orphaned Sessions**: Teardown mandatory. Call `delete` in cleanup block.5152## 📁 Evidence5354`.appium-mcp/<session>/`: `<AC|step>-<before|after>.png` (nav shots at `maxWidth` budget, verdict full-res), `<label>.source.xml` from `appium_get_page_source`, `perf.json`, `video.url`. Walkthrough records `driver:` + `evidence_dir:`.5556## ✅ Evaluation Criteria5758- **Cleanup Rate**: 100% session closure.59- **Visual Accuracy**: Coordinate-based taps land within 5% of target center.60- **Security**: No secrets in tool arguments or logs.6162## 🔗 References6364- **Visual Testing**: [common-mobile-visual-testing](../../common/common-mobile-visual-testing/SKILL.md) — Methodology for what to verify.65- **Driver Ladder**: [driver-ladder](references/driver-ladder.md) — prerequisites per rung, server env, canonical tools.66- **Setup**: [setup](references/setup.md) — install, MCP registration snippet, security, alternatives not adopted.67- **LambdaTest Setup**: [lambdatest-cloud-setup](references/lambdatest-cloud-setup.md) — RDC configuration.68- **Tool Cheatsheet**: [tool-cheatsheet](references/tool-cheatsheet.md) — Fast copy-paste args.69- **Project Context**: [project-context](references/project-context.md) — Project-specific overlays/macros.
HoangNguyen0403