Back to Details

qa-testing-android

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QA Testing (Android)

Android QA测试

Android testing automation with Espresso, UIAutomator, and Compose Testing.
Core References: Android Testing Docs, Espresso, Compose Testing
使用Espresso、UIAutomator和Compose Testing实现Android测试自动化。
核心参考文档：Android测试文档、Espresso、Compose Testing

Quick Reference

快速参考

TaskCommand
List emulators
emulator -list-avds
Start emulator
emulator @<avd_name>
List devices
adb devices
Install APK
adb install -r <path-to-apk>
Run unit tests
./gradlew test
Run instrumented tests (connected)
./gradlew connectedAndroidTest
Run instrumented tests (GMD)
./gradlew <device><variant>AndroidTest
List GMD tasks`./gradlew tasks --all
Clear app data
adb shell pm clear <applicationId>
任务命令
列出模拟器
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>

Quick Start (2026 Defaults)

快速入门（2026默认配置）

  • Prefer Gradle Managed Devices (GMD) + ATD images for CI; use 
    connectedAndroidTest
    for local ad-hoc runs.
  • Enable test isolation via AndroidX Test Orchestrator for instrumented tests.
  • Disable animations via Gradle 
    testOptions
    (preferred) instead of per-runner ADB steps.
  • Keep selectors stable: 
    withId()
    (Views), 
    testTag
    (Compose), resource-id/content-desc (UIAutomator).
Recommended Gradle defaults for stable instrumented tests (version catalog names vary by project):
kotlin
android {
    testOptions {
        animationsDisabled = true
        execution = "ANDROIDX_TEST_ORCHESTRATOR"
    }
}

dependencies {
    androidTestUtil(libs.androidx.test.orchestrator)
}
  • CI环境优先使用Gradle Managed Devices (GMD) + ATD镜像；本地临时运行使用
    connectedAndroidTest
    。
  • 为插桩测试启用AndroidX Test Orchestrator以实现测试隔离。
  • 通过Gradle 
    testOptions
    禁用动画（推荐方式），而非每次运行时执行ADB步骤。
  • 使用稳定的选择器：
    withId()
    （Views）、
    testTag
    （Compose）、resource-id/content-desc（UIAutomator）。
以下是稳定插桩测试推荐的Gradle默认配置（版本目录名称因项目而异）：
kotlin
android {
    testOptions {
        animationsDisabled = true
        execution = "ANDROIDX_TEST_ORCHESTRATOR"
    }
}

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

When to Use

使用场景

  • Debug or stabilize flaky Android UI tests
  • Add Espresso tests for View-based UIs
  • Add Compose UI tests for composables
  • Add UIAutomator tests for system UI or cross-app flows
  • Set up an Android test gate in CI
  • 调试或稳定不稳定的Android UI测试
  • 为基于View的UI添加Espresso测试
  • 为Composable添加Compose UI测试
  • 为系统UI或跨应用流程添加UIAutomator测试
  • 在CI中设置Android测试关卡

Inputs to Gather

需要收集的信息

  • UI stack: Views, Compose, or mixed
  • Test layer: unit, Robolectric, instrumented UI, UIAutomator/system
  • CI target: PR gate vs nightly vs release; emulator vs device farm
  • Device matrix: min/target API, form factors, locales (if relevant)
  • Flake symptoms: timeouts, missing nodes, idling/sync, device-only issues
  • App seams: DI hooks for fakes, feature flags, test accounts/test data
  • UI技术栈：Views、Compose或混合栈
  • 测试分层：单元测试、Robolectric测试、插桩UI测试、UIAutomator/系统测试
  • CI目标：PR关卡、夜间构建或发布测试；模拟器或设备农场
  • 设备矩阵：最低/目标API级别、设备形态、语言区域（如相关）
  • Flake测试症状：超时、节点缺失、idle/同步问题、仅设备端出现的问题
  • 应用可测试点：DI钩子用于模拟数据、功能开关、测试账号/测试数据

Testing Layers

测试分层

LayerFrameworkScope
UnitJUnit + MockitoJVM, no Android
Unit (Android)RobolectricJVM, simulated
UI (Views)EspressoInstrumented
UI (Compose)Compose TestingInstrumented
SystemUIAutomatorCross-app
分层框架范围
单元测试JUnit + MockitoJVM环境，无需Android
Android单元测试RobolectricJVM环境，模拟Android
UI测试（Views）Espresso需设备/模拟器运行
UI测试（Compose）Compose Testing需设备/模拟器运行
系统测试UIAutomator跨应用

Core Principles (Stability)

核心原则（稳定性）

Device Matrix

设备矩阵

  • Default: emulators for PR gates; real devices for release
  • Cover: min supported API level, target API level, plus tablet/foldable if supported
  • 默认配置：PR关卡使用模拟器；发布测试使用真实设备
  • 覆盖范围：最低支持API级别、目标API级别，若支持则包含平板/折叠屏

Flake Control

Flake测试控制

  • Prefer Gradle 
    testOptions { animationsDisabled = true }
    for instrumented tests
  • Use AndroidX Test Orchestrator to isolate state and recover from crashes
  • Use IdlingResources / Compose idling + 
    waitUntil
    instead of sleeps
  • Mock network with 
    MockWebServer
    (or your DI fake) and avoid live backends
  • Reset app state per test (test account/data, storage, feature flags)
  • 插桩测试优先使用Gradle 
    testOptions { animationsDisabled = true }
  • 使用AndroidX Test Orchestrator隔离状态并从崩溃中恢复
  • 使用IdlingResources / Compose idle + 
    waitUntil
    替代休眠
  • 使用
    MockWebServer
    （或DI模拟）模拟网络，避免使用真实后端
  • 每次测试重置应用状态（测试账号/数据、存储、功能开关）

Writing Tests

编写测试

  • Espresso (Views): open 
    references/espresso-patterns.md
  • Compose: open 
    references/compose-testing.md
  • UIAutomator (system/cross-app): open 
    references/uiautomator.md
  • Espresso（Views）：打开
    references/espresso-patterns.md
  • Compose：打开
    references/compose-testing.md
  • UIAutomator（系统/跨应用）：打开
    references/uiautomator.md

Workflows

工作流程

Add a New UI Test (Instrumented)

添加新的UI测试（插桩式）

  • Pick framework: Espresso (Views) vs Compose Testing vs UIAutomator boundary.
  • Add stable selectors: View 
    id
    , Compose 
    Modifier.testTag
    , system 
    resource-id
    /
    content-desc
    .
  • Control externals: fake/mock network + deterministic test data.
  • Add waits: IdlingResources / Compose idling + 
    waitUntil
    (avoid sleeps).
  • Run locally: 
    ./gradlew connectedAndroidTest
    (or a single test via runner args).
  • 选择框架：Espresso（Views） vs Compose Testing vs UIAutomator（边界场景）
  • 添加稳定选择器：View的
    id
    、Compose的
    Modifier.testTag
    、系统的
    resource-id
    /
    content-desc
  • 控制外部依赖：模拟网络 + 确定性测试数据
  • 添加等待：IdlingResources / Compose idle + 
    waitUntil
    （避免休眠）
  • 本地运行：
    ./gradlew connectedAndroidTest
    （或通过运行参数指定单个测试）

Diagnose a Flaky Instrumented Test

诊断不稳定的插桩测试

  • Confirm reproduces: run the test 10x; isolate to one device/API if needed.
  • Remove nondeterminism: network, clock/timezone, locale, feature flags, animations.
  • Replace sleeps with idling/explicit waits; validate your IdlingResource actually idles.
  • Capture artifacts: logcat + screenshot + screen recording for failures.
  • If still flaky, isolate app state (orchestrator + clear data) and bisect the interaction steps.
  • 确认可复现：运行测试10次；若需则隔离到特定设备/API
  • 移除非确定性因素：网络、时钟/时区、语言区域、功能开关、动画
  • 用idling/显式等待替代休眠；验证你的IdlingResource确实能进入idle状态
  • 捕获artifacts：logcat + 截图 + 录屏用于故障分析
  • 若仍不稳定，隔离应用状态（Orchestrator + 清除数据）并二分排查交互步骤

Add a CI Gate (Preferred: GMD)

添加CI关卡（推荐：GMD）

  • Configure GMD + ATD images (see 
    references/gradle-managed-devices.md
    ).
  • Run PR gate on a small matrix; expand via groups for nightly/release.
  • Ensure artifacts upload on failure: 
    **/build/reports/androidTests/
    , screenshots/logcat.
  • 配置GMD + ATD镜像（参见
    references/gradle-managed-devices.md
    ）
  • PR关卡运行小型设备矩阵；夜间/发布测试扩展矩阵
  • 确保测试失败时上传artifacts：
    **/build/reports/androidTests/
    、截图/logcat

ADB Commands (Triage)

ADB命令（问题排查）

bash
undefined
bash
undefined

Screenshot

截图

adb exec-out screencap -p > screenshot.png
adb exec-out screencap -p > screenshot.png

Screen recording

录屏

adb shell screenrecord /sdcard/demo.mp4
undefined
adb shell screenrecord /sdcard/demo.mp4
undefined

CI Integration

CI集成

Preferred: Gradle Managed Devices (GMD). See 
references/gradle-managed-devices.md
.
yaml
undefined
推荐方案：Gradle Managed Devices (GMD)。参见
references/gradle-managed-devices.md
。
yaml
undefined

.github/workflows/android.yml

.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
undefined
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
undefined

Navigating References

参考文档导航

The reference guides are intentionally large; search within them instead of loading everything:
  • 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
参考文档内容较多，建议直接搜索所需内容而非全部阅读：
  • 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

Do / Avoid

建议与禁忌

Do

建议

  • Prefer orchestrator + per-test isolation for instrumented tests
  • Use IdlingResources / 
    waitUntil
    for async waits
  • Use Robot/Page Object patterns for readability and reuse
  • Run a small device matrix on PRs; expand on nightly/release
  • 插桩测试优先使用Orchestrator + 单测隔离
  • 异步等待使用IdlingResources / 
    waitUntil
  • 使用Robot/Page Object模式提升可读性和复用性
  • PR运行小型设备矩阵；夜间/发布测试扩展矩阵

Avoid

禁忌

  • Thread.sleep()
    for synchronization
  • Tests depending on live network/backends
  • Flaky selectors (localized text, position-only selectors)
  • 使用
    Thread.sleep()
    进行同步
  • 测试依赖真实网络/后端
  • 使用不稳定的选择器（本地化文本、仅基于位置的选择器）

Resources

资源

ResourcePurpose
references/espresso-patterns.mdEspresso matchers, actions
references/compose-testing.mdCompose testing guide
references/uiautomator.mdUIAutomator patterns (system UI)
references/gradle-managed-devices.mdManaged Devices for CI
data/sources.jsonDocumentation links
资源用途
references/espresso-patterns.mdEspresso匹配器、操作指南
references/compose-testing.mdCompose测试指南
references/uiautomator.mdUIAutomator模式（系统UI）
references/gradle-managed-devices.mdCI用Managed Devices指南
data/sources.json文档链接集合

Templates

模板

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

Related Skills

相关技能

SkillPurpose
software-mobileAndroid development
qa-testing-strategyTest strategy
qa-testing-mobileCross-platform mobile
技能用途
software-mobileAndroid开发
qa-testing-strategy测试策略
qa-testing-mobile跨平台移动测试