name: qa-testing-android description: 使用Espresso、UIAutomator和Compose Testing进行Android测试；分层策略、控制flake、设备矩阵、CI集成和ADB自动化。

QA 测试 (Android)

Android测试自动化，使用Espresso、UIAutomator和Compose Testing。

核心参考: Android 测试文档, Espresso, Compose Testing

快速参考

任务	命令
列出模拟器	`emulator -list-avds`
启动模拟器	`emulator @<avd_name>`
列出设备	`adb devices`
安装 APK	`adb install -r <path-to-apk>`
运行单元测试	`./gradlew test`
运行仪器化测试（连接设备）	`./gradlew connectedAndroidTest`
运行仪器化测试（GMD）	`./gradlew <device><variant>AndroidTest`
列出 GMD 任务	`./gradlew tasks --all
清除应用数据	`adb shell pm clear <applicationId>`

快速开始 (2026 默认设置)

偏好 Gradle 管理设备 (GMD) + ATD 镜像用于 CI；使用 connectedAndroidTest 进行本地临时运行。
启用测试隔离通过 AndroidX 测试编排器用于仪器化测试。
通过 Gradle testOptions（首选）禁用动画，而不是每个运行器的 ADB 步骤。
保持选择器稳定：withId()（视图）、testTag（Compose）、资源-id/内容描述符（UIAutomator）。

推荐 Gradle 默认设置用于稳定的仪器化测试（项目中的版本目录名称可能不同）：

android {
    testOptions {
        animationsDisabled = true
        execution = "ANDROIDX_TEST_ORCHESTRATOR"
    }
}

dependencies {
    androidTestUtil(libs.androidx.test.orchestrator)
}

何时使用

调试或稳定 flaky 的 Android UI 测试
为基于视图的 UI 添加 Espresso 测试
为可组合项添加 Compose UI 测试
为系统 UI 或跨应用流程添加 UIAutomator 测试
在 CI 中设置 Android 测试门

收集输入

UI 栈：视图、Compose 或混合
测试层：单元、Robolectric、仪器化 UI、UIAutomator/系统
CI 目标：PR 门 vs 夜间 vs 发布；模拟器 vs 设备农场
设备矩阵：最小/目标 API、表单因素、本地化（如果相关）
Flake 症状：超时、缺失节点、空闲/同步、仅设备问题
应用接缝：用于伪造的 DI 钩子、功能标志、测试账户/测试数据

测试层

层	框架	范围
单元	JUnit + Mockito	JVM，无 Android
单元（Android）	Robolectric	JVM，模拟
UI（视图）	Espresso	仪器化
UI（Compose）	Compose Testing	仪器化
系统	UIAutomator	跨应用

核心原则（稳定性）

设备矩阵

默认：模拟器用于 PR 门；真实设备用于发布
覆盖：最小支持 API 级别、目标 API 级别，加上平板/可折叠设备（如果支持）

Flake 控制

偏好 Gradle testOptions { animationsDisabled = true } 用于仪器化测试
使用 AndroidX 测试编排器隔离状态并从崩溃中恢复
使用 IdlingResources / Compose idling + waitUntil 而不是睡眠
用 MockWebServer（或你的 DI 伪造）模拟网络并避免实时后端
每个测试重置应用状态（测试账户/数据、存储、功能标志）

编写测试

Espresso（视图）：打开 references/espresso-patterns.md
Compose：打开 references/compose-testing.md
UIAutomator（系统/跨应用）：打开 references/uiautomator.md

工作流

添加新 UI 测试（仪器化）

选择框架：Espresso（视图）vs Compose Testing vs UIAutomator 边界。
添加稳定选择器：视图 id、Compose Modifier.testTag、系统 resource-id/content-desc。
控制外部因素：伪造/模拟网络 + 确定性测试数据。
添加等待：IdlingResources / Compose idling + waitUntil（避免睡眠）。
本地运行：./gradlew connectedAndroidTest（或通过运行器参数运行单个测试）。

诊断 Flaky 仪器化测试

确认可复现：运行测试 10 次；如果需要，隔离到一个设备/API。
去除非确定性：网络、时钟/时区、本地化、功能标志、动画。
用空闲/显式等待替换睡眠；验证你的 IdlingResource 实际上空闲。
捕获工件：失败时的 logcat + 截图 + 屏幕录制。
如果仍然 flaky，隔离应用状态（编排器 + 清除数据）并二分交互步骤。

添加 CI 门（首选：GMD）

配置 GMD + ATD 镜像（见 references/gradle-managed-devices.md）。
在小型矩阵上运行 PR 门；通过组扩展用于夜间/发布。
确保失败时上传工件：**/build/reports/androidTests/、截图/logcat。

ADB 命令（故障排除）

# 截图
adb exec-out screencap -p > screenshot.png

# 屏幕录制
adb shell screenrecord /sdcard/demo.mp4

CI 集成

首选：Gradle 管理设备 (GMD)。见 references/gradle-managed-devices.md。

# .github/workflows/android.yml
name: Android CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      - uses: gradle/actions/setup-gradle@v3
      - run: ./gradlew test pixel6api34DebugAndroidTest

导航参考

参考指南故意很大；在其中搜索而不是加载所有内容：

rg -n \"^## \" frameworks/shared-skills/skills/qa-testing-android/references/compose-testing.md
rg -n \"Idling|waitUntil|Synchronization\" frameworks/shared-skills/skills/qa-testing-android/references/compose-testing.md
rg -n \"RecyclerView|Intents\" frameworks/shared-skills/skills/qa-testing-android/references/espresso-patterns.md

做 / 避免

做

偏好编排器 + 每个测试隔离用于仪器化测试
使用 IdlingResources / waitUntil 进行异步等待
使用 Robot/页面对象模式提高可读性和重用性
在 PR 上运行小型设备矩阵；在夜间/发布上扩展

避免

Thread.sleep() 用于同步
依赖实时网络/后端的测试
Flaky 选择器（本地化文本、仅基于位置的选择器）

资源

资源	用途
references/espresso-patterns.md	Espresso 匹配器、动作
references/compose-testing.md	Compose 测试指南
references/uiautomator.md	UIAutomator 模式（系统 UI）
references/gradle-managed-devices.md	用于 CI 的管理设备
data/sources.json	文档链接

模板

模板	用途
assets/template-android-test-checklist.md	稳定性检查清单

技能	用途
software-mobile	Android 开发
qa-testing-strategy	测试策略
qa-testing-mobile	跨平台移动

安卓自动化测试 qa-testing-android