android-emulator-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Android 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-ui
  • android-permissions-activity-results
  • 当请求涉及以下内容时,使用此 skill:Android 模拟器自动化、ADB 语义化 UI 自动化、UIAutomator dump 和 tap。
  • 主要结果:使用语义化 ADB 和 UIAutomator 工作流,让 Agent 检查、启动并与 Android 应用交互。
  • 当 Agent 需要启动 APK、检查当前屏幕,或执行无需编写 Espresso 或 Compose UI 测试的确定性交互时,使用此 skill。
  • 当任务范围扩大时,移交给以下 skill:
  • android-testing-ui
  • android-permissions-activity-results

Workflow

工作流

  1. Verify the Android SDK,
    adb
    , the target device or emulator, and boot completion before attempting interaction.
  2. Install or launch the target app with explicit package awareness so the request stays tied to the right artifact.
  3. Dump the current UI hierarchy and prefer semantic selectors such as text, content description, or resource ID over raw coordinates.
  4. Perform the smallest interaction that proves the workflow and re-dump the screen when state changes matter.
  5. Hand off long-lived regression coverage to UI tests once the automation path is understood.
  1. 在尝试交互之前,验证 Android SDK、
    adb
    、目标设备或模拟器以及启动完成状态。
  2. 在明确包名的情况下安装或启动目标应用,确保请求始终关联正确的构建产物。
  3. Dump 当前 UI 层级,并优先使用文本、content description 或 resource ID 等语义化选择器,而不是原始坐标。
  4. 执行能够验证工作流的最小交互;当界面状态变化很重要时,重新 dump 屏幕。
  5. 自动化路径明确后,将长期回归测试覆盖移交给 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 测试。

Official References

官方参考