android-emulator-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAndroid Emulator Automation
Android 模拟器自动化
When To Use
何时使用
- Use this skill when the request is about: android emulator automation, adb semantic ui automation, uiautomator dump and tap.
- Primary outcome: Use semantic ADB and UIAutomator workflows to inspect, launch, and interact with Android apps from agents.
- Reach for this skill when an agent needs to launch an APK, inspect the current screen, or perform a deterministic interaction without writing Espresso or Compose UI tests.
- Handoff skills when the scope expands:
android-testing-uiandroid-permissions-activity-results
- 当请求涉及以下内容时,使用此 skill:Android 模拟器自动化、ADB 语义化 UI 自动化、UIAutomator dump 和 tap。
- 主要结果:使用语义化 ADB 和 UIAutomator 工作流,让 Agent 检查、启动并与 Android 应用交互。
- 当 Agent 需要启动 APK、检查当前屏幕,或执行无需编写 Espresso 或 Compose UI 测试的确定性交互时,使用此 skill。
- 当任务范围扩大时,移交给以下 skill:
android-testing-uiandroid-permissions-activity-results
Workflow
工作流
- Verify the Android SDK, , the target device or emulator, and boot completion before attempting interaction.
adb - Install or launch the target app with explicit package awareness so the request stays tied to the right artifact.
- Dump the current UI hierarchy and prefer semantic selectors such as text, content description, or resource ID over raw coordinates.
- Perform the smallest interaction that proves the workflow and re-dump the screen when state changes matter.
- Hand off long-lived regression coverage to UI tests once the automation path is understood.
- 在尝试交互之前,验证 Android SDK、、目标设备或模拟器以及启动完成状态。
adb - 在明确包名的情况下安装或启动目标应用,确保请求始终关联正确的构建产物。
- Dump 当前 UI 层级,并优先使用文本、content description 或 resource ID 等语义化选择器,而不是原始坐标。
- 执行能够验证工作流的最小交互;当界面状态变化很重要时,重新 dump 屏幕。
- 自动化路径明确后,将长期回归测试覆盖移交给 UI 测试。
Guardrails
防护措施
- Prefer semantic selectors to pixel coordinates; only fall back to coordinates when the UI tree is missing the required metadata.
- Treat automation as an inspection and smoke tool, not a replacement for deterministic UI tests.
- Verify device state, package name, and boot completion before issuing input commands.
- Keep the scripts safe for CI by avoiding destructive shell commands or device-wide settings changes.
- 优先使用语义化选择器而非像素坐标;仅当 UI 树缺少所需元数据时才回退到坐标。
- 将自动化视为检查和冒烟测试工具,而不是确定性 UI 测试的替代品。
- 执行输入命令之前,验证设备状态、包名和启动完成情况。
- 避免破坏性 shell 命令或设备级设置更改,以确保脚本在 CI 中安全运行。
Anti-Patterns
反模式
- Hard-coding coordinates when text or resource IDs are available.
- Running emulator commands before the device is boot-complete.
- Treating flaky one-off automation as proof of a stable UI workflow.
- Mixing app install, interaction, and log scraping into one opaque script with no intermediate output.
- 在可以使用文本或 resource ID 时硬编码坐标。
- 设备尚未启动完成就运行模拟器命令。
- 将容易偶发的一次性自动化视为稳定 UI 工作流的证明。
- 将应用安装、交互和日志抓取混合到一个不透明脚本中,且不输出任何中间结果。
Examples
示例
Happy path
正常路径
- Scenario: Build the Compose fixture, install it on an emulator, and dump the current OrbitTasks screen.
- Command:
bash skills/android-emulator-automation/scripts/run_examples.sh
- 场景:构建 Compose fixture,将其安装到模拟器中,并 dump 当前的 OrbitTasks 屏幕。
- 命令:
bash skills/android-emulator-automation/scripts/run_examples.sh
Edge case
边界情况
- Scenario: Launch a preinstalled app and target a single semantic control without relying on screen coordinates.
- Command:
python3 skills/android-emulator-automation/scripts/navigator.py --find-text "Blocked" --tap
- 场景:启动预装应用并定位单个语义化控件,无需依赖屏幕坐标。
- 命令:
python3 skills/android-emulator-automation/scripts/navigator.py --find-text "Blocked" --tap
Failure recovery
失败恢复
- Scenario: Confirm the device is discoverable and UIAutomator can dump the hierarchy before chasing a selector bug.
- Command:
python3 skills/android-emulator-automation/scripts/device_health.py --json
- 场景:在排查选择器问题之前,确认设备可以被发现,并且 UIAutomator 能够 dump UI 层级。
- 命令:
python3 skills/android-emulator-automation/scripts/device_health.py --json
Done Checklist
完成检查清单
- The target package, device serial, and current screen are explicit.
- Semantic selectors were preferred over coordinates.
- The automation path is reproducible in local development and CI.
- The request hands off to UI testing when the workflow needs regression coverage.
- 明确指定目标包名、设备序列号和当前屏幕。
- 优先使用语义化选择器而非坐标。
- 自动化路径可以在本地开发和 CI 中复现。
- 当工作流需要回归测试覆盖时,将其移交给 UI 测试。