android-emulator-automation

Android 模拟器自动化

适用场景

• 当请求涉及 Android 模拟器自动化、adb 语义 UI 自动化、uiautomator 转储和点击时，使用此技能。
• 主要目标：使用语义化 ADB 和 UIAutomator 工作流，从 Agent 检查、启动和操作 Android 应用。
• 当 Agent 需要启动 APK、检查当前屏幕，或执行确定性操作而无需编写 Espresso 或 Compose UI 测试时，使用此技能。
• 当范围扩大时，移交给以下技能：
• android-testing-ui
• android-permissions-activity-results

工作流

1. 在尝试交互前，确认 Android SDK、adb、目标设备或模拟器均可用，且设备已完成启动。
2. 安装或启动目标应用时，明确指定包名，确保请求关联到正确的应用产物。
3. 转储当前 UI 层级，并优先使用文本、内容描述或资源 ID 等语义选择器，而非原始坐标。
4. 执行能验证工作流的最小操作；当状态变化很重要时，重新转储屏幕。
5. 理解自动化路径后，将长期回归覆盖移交给 UI 测试。

防护措施

• 优先使用语义选择器而非像素坐标；仅当 UI 树缺少所需元数据时，才使用坐标。
• 将自动化视为检查和冒烟测试工具，而非确定性 UI 测试的替代品。
• 执行输入命令前，确认设备状态、包名和启动完成情况。
• 为确保脚本适用于 CI，避免使用破坏性 shell 命令或更改设备范围的设置。

反模式

• 在有可用文本或资源 ID 时硬编码坐标。
• 在模拟器启动完成前运行命令。
• 将不稳定的一次性自动化视为 UI 工作流稳定的证明。
• 将应用安装、交互和日志抓取混入一个不透明且没有中间输出的脚本。

示例

顺利流程

• 场景：构建 Compose 测试夹具，将其安装到模拟器上，并转储当前的 OrbitTasks 屏幕。
• 命令：bash skills/android-emulator-automation/scripts/run_examples.sh

边缘情况

• 场景：启动预装应用，并在不依赖屏幕坐标的情况下定位单个语义控件。
• 命令：python3 skills/android-emulator-automation/scripts/navigator.py --find-text "Blocked" --tap

故障恢复

• 场景：确认设备可被发现，且 UIAutomator 能转储层级，然后再排查选择器问题。
• 命令：python3 skills/android-emulator-automation/scripts/device_health.py --json

完成检查清单

• 已明确目标包名、设备序列号和当前屏幕。
• 优先使用了语义选择器，而非坐标。
• 自动化路径可在本地开发环境和 CI 中复现。
• 当工作流需要回归覆盖时，请求已移交给 UI 测试。

官方参考资料

• https://developer.android.com/studio/run/emulator
• https://developer.android.com/tools/adb
• https://developer.android.com/training/testing/other-components/ui-automator
• https://developer.android.com/studio/test/command-line