qa-testing-android

QA 测试（Android）

使用 Espresso、UI Automator、Compose Testing、截图测试和自适应 UI 验证进行 Android 测试自动化。

核心参考资料：Android 测试文档、Build-Managed Devices、Compose Testing、UI Automator、截图测试、无障碍检查

快速参考

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

平台版本

固定版本前请先查询当前版本；此表仅列出兼容性规则。

组件	当前版本查询位置	稳定性说明
Android / API 级别	Android 开发者版本说明	最新 OS 版本并不自动成为目标 API 要求；请参阅下文“Google Play 目标 API 政策”
AGP	https://developer.android.com/build/releases/about-agp	根据已安装的 AGP 次版本，从兼容性表中选择 Gradle Wrapper/JDK；仅匹配主版本并不足够
Robolectric	https://github.com/robolectric/robolectric/releases	Robolectric 4.17 增加了对 SDK 37 的支持。SDK 36+ 需要 JDK 21
UI Automator	https://developer.android.com/jetpack/androidx/releases/test-uiautomator	2.4 API 边界新增了 uiAutomator {} DSL；请选择项目批准的版本
Compose Preview 截图测试	Android Studio / AGP 版本说明	分别检查插件与 AGP 测试套件的配置，以及命令行与 IDE 的要求；请参阅 screenshot-testing.md
ATD 映像	模拟器系统映像列表	在托管设备指南和 SDK Manager 中检查支持的 API 映像；ATD 会停用硬件渲染
Maestro	Maestro 版本说明	新 API 级别的支持可能会先进入本地 CLI，再进入 Maestro Cloud；以新 Android 版本为目标前请先检查

Google Play 目标 API 政策（每次发布切换前检查）

选择发布矩阵前，请阅读适用于应用外形规格、提交类型、截止日期和延期状态的目标 API 要求。 新应用提交与现有应用的可用性遵循不同规则；私有应用和 Wear/TV/Automotive/XR 可能有例外。记录适用要求，并在构建产物中验证应用的 targetSdk。

快速开始

• 在 CI 中优先使用构建管理的设备（GMD），并在测试套件和支持的 API 级别允许时使用 ATD 镜像；本地临时运行使用 connectedAndroidTest。
• 从支持的镜像列表中选择 ATD API；所需 API 或渲染路径不可用时，使用标准镜像。
• 对需要严格隔离的插桩测试套件，启用 Android Test Orchestrator 和 clearPackageData。
• 在 Gradle 中禁用动画，不要在测试流程中临时使用 ADB 步骤。
• 将截图测试作为独立的快速回归层：使用 Compose Preview Screenshot Testing 覆盖 @Preview，使用 Paparazzi 或 Roborazzi 进行 JVM 渲染；只有在硬件保真度很重要时，才使用基于设备的快照。
• 明确覆盖自适应布局：紧凑和扩展布局、受支持时的平板或折叠屏路径，以及产品依赖这些变化时的方向切换。
• 尽早将无障碍检查加入现有 UI 测试，而不是只在手动测试阶段处理无障碍。

稳定插桩测试的 Gradle 默认配置：

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

        emulatorSnapshots {
            enableForTestFailures = true
            maxSnapshotsForTestFailures = 2
        }
    }
}

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

如果依赖插桩测试之间的隔离，还应在 Gradle 或 CI 配置中设置 clearPackageData=true 等运行器参数。

需要收集的信息

• UI 技术栈：Views、Compose，或混合使用
• 测试层：单元测试、Robolectric、插桩 UI 测试、截图测试、UI Automator、宏基准测试
• CI 目标：PR 门禁、夜间构建或发布；托管模拟器或设备农场
• 设备矩阵：最低支持 API、目标 API、屏幕类别、区域设置、深色模式、外形规格
• 不稳定表现：超时、节点缺失、空闲或同步问题、仅渲染器出现差异、仅设备上失败
• 无障碍要求：触控目标、标签、对比度、TalkBack 关键流程
• 应用接缝：用于替身的 DI 接入点、功能标志、测试账号、确定性时钟、图片加载器

测试层

层级	框架	范围
单元测试	JUnit + Mockito	JVM，无 Android
单元测试（Android）	Robolectric	JVM，模拟框架
UI（Views）	Espresso	插桩测试
UI（Compose）	Compose Testing	插桩测试；通过明确配置 Robolectric 也可在 JVM 上运行
自适应 UI	Espresso Device API + DeviceConfigurationOverride	插桩测试或主机辅助
截图测试	Compose Preview Screenshot Testing、Paparazzi、Roborazzi	JVM 或插桩测试
系统测试	UI Automator	跨应用、系统 UI、基准测试驱动程序

核心原则（稳定性）

设备矩阵

• 默认使用模拟器作为 PR 门禁；对发布关键流程使用真机或设备农场。
• 至少覆盖最低支持 API 和目标 API；如果产品提供扩展布局，还应增加平板或折叠屏覆盖。
• 根据布局行为规划自适应覆盖，不要只看设备的营销名称。

控制不稳定因素

• 对插桩测试，优先使用 testOptions { animationsDisabled = true }。
• 当共享应用状态或进程崩溃导致测试间状态泄漏时，使用 Android Test Orchestrator。
• 使用 IdlingResources、Compose 同步、waitUntil 或 UI Automator 条件，而不是休眠等待。
• 使用 MockWebServer 或 DI 替身模拟网络；避免在 CI 中连接线上后端。
• 确保截图测试具有确定性：固定字体、区域设置、时钟、网络图片和种子数据。
• 在 CI 中保留测试失败快照或截图，让失败有对应产物，而不只是堆栈跟踪。

无障碍与自适应覆盖

• 在高价值 Espresso 或 Compose 流程所在的同一测试套件中运行无障碍检查。
• 有意验证紧凑和扩展布局状态；不要假设仅针对手机的测试矩阵能够覆盖响应式布局。
• 优先使用稳定的选择器：Views 使用 withId()，Compose 使用 testTag，UI Automator 使用 resource-id 或内容描述。

专家判断（清单遗漏之处）

模拟器与实体设备——实际取舍

检查清单上会写着“CI 使用模拟器，发布前使用真实设备”。真正需要判断的是：哪些实体设备信号值得投入成本：

• PR 门禁适合使用模拟器（最好由构建流程管理；无需硬件保真度时使用 ATD），因为它们具有确定性、可随时销毁，而且不会受到温度、电池或 OEM 差异的干扰，否则这些因素可能被误判为应用 Bug。
• 只有当 OEM 或硬件行为确实构成风险时，实体设备或设备云才值得投入成本：相机拍摄、生物识别身份验证、NFC/BLE、真实 Doze/App Standby 状态下后台任务的可靠性、折叠设备的转轴/姿态转换，以及在真实 Play Integrity 检查下行为有所不同的支付 SDK。如果流程中不涉及这些情况，运行设备云测试只是做样子，毫无实际信号可言。
• 一个常见的反模式是每晚在设备云上运行整套回归测试，以“增强信心”。这会消耗预算，却不会改变你实际能捕获的故障类型——设备云上大多数失败，在受管模拟器上也会出现，而且速度更快、成本更低。设备云的运行时长应留给上述少数与硬件紧密相关的流程，并将这些流程与常规回归套件分开设门禁。
• 选择模拟器系统映像本身也需要判断，而不只是“Google 还是 AOSP”：对于依赖服务的流程，要确认映像提供所需的服务和分发渠道；任何基于硬件渲染像素进行断言的测试，都需要使用非 ATD 映像；如果 ATD 支持的 API 和精简后的系统范围适合该流程，就使用 ATD，否则使用标准映像。Google API 映像无法证明依赖 Play 商店或分发渠道的行为；应单独检查该渠道。

Android Flake 分类（按类别诊断，而非按症状）

泛泛地将问题归为“测试不稳定”，并反复重跑，只会浪费时间。Android UI 测试的不稳定性集中在少数几类根因中——先判断问题属于哪一类，再考虑重试：

1. 同步缺口 — Espresso/Compose 无法等待的异步操作。典型表现：在本地快速机器上通过，在 CI 负载下失败；出现 NoMatchingViewException，或断言针对过时的加载状态触发。根因几乎总是未注册的 IdlingResource（Espresso），或缺少 waitUntil/同步的 TestDispatcher（Compose/coroutines）——有关注册陷阱，请参阅 references/espresso-patterns.md。
2. 动画/过渡时序 — Espresso 检查视图树时，窗口动画或属性动画仍在运行。CI 中优先使用 Gradle 级别的 testOptions { animationsDisabled = true }。仅当 Gradle 标志不可用时（例如，使用不支持该标志的本地模块或较早版本的 Gradle），才退而使用 references/espresso-patterns.md 中按测试设置 adb 的 DisableAnimationsRule 模式——请在自己的测试套件中将其标记为“legacy”，因为如果两种机制同时存在，它们可能会在不报错的情况下产生冲突。
3. 语义树合并（仅限 Compose） — Material 组件（例如，Button 内的 Text）中的子级 testTag 对 onNodeWithTag 不可见，因为合并后的后代会折叠到父节点中；或者，多值断言（如 assertTextEquals("Save")）与合并节点的完整 Text 列表不匹配。文本查找器（如 onNodeWithText）默认仍会匹配合并后的父节点——这不是“找不到任何内容”的问题，也完全不是时序问题；不要用等待循环来“修复”。有关修正后的合并树陷阱，请参阅 references/compose-testing.md。从 v1 迁移到 v2 也可能暴露排队的协程任务；请将其归类为同步缺口（#1），并参考 references/compose-testing.md 中的迁移部分。
4. 测试间状态泄漏 — 前一个测试留下了 SharedPreferences、数据库行或单例状态，而下一个测试并不预期这种状态。典型表现：失败取决于执行顺序，单独运行失败测试时却不再失败。请使用 Test Orchestrator + clearPackageData 修复，不要调整测试顺序。
5. Doze / App Standby / 后台限制 — 依赖后台任务（WorkManager、FCM、前台服务）的测试，在设备电源管理状态下的表现可能不同于刚启动的模拟器。这种情况几乎只出现在实体设备或长时间运行的 CI 机器上，在短暂使用的托管设备上很少见——如果后台任务测试只在某一种环境中不稳定，应先怀疑电源管理状态，而非测试本身。
6. 渲染器/保真度差异 — 截图差异确实存在，却毫无实际意义：ATD 禁用了硬件渲染，CI 与本地的 GPU 驱动不同，或不同 OS 镜像之间存在字体替换。可通过在用于记录截图的同类镜像上重新运行相同的黄金图生成流水线，判断这是实际的视觉回归，还是渲染差异。
7. 非确定性测试数据或时钟 — 实时网络调用、真实的 System.currentTimeMillis()，或未设种子的随机数据泄漏到了断言或截图黄金图中。这些都可以通过 mock 处理；如果问题仍然发生，通常意味着新增屏幕后没有复用已有的 fake。

测试不稳定时，先明确它属于上述七类中的哪一类，再动测试——#1 的修复（注册/等待）无法解决 #4（隔离/清除状态），而把 #2 的修复（禁用动画）用于 #5（Doze）问题也毫无作用。

Compose 应用的测试金字塔现状

经典的测试金字塔（大量单元测试、一些集成测试、少量端到端测试）仍然适用，但 Compose 改变了中间层的位置：

• createComposeRule() 仍会在底层使用 ComponentActivity 承载你的内容，并在设备或模拟器上运行插桩测试，除非该模块也在 test/ 下通过 Robolectric 运行——它并不会自动变成无需设备的测试。它确实能避开你自己的 Activity、DI 图和导航。只要组合函数不需要真实导航、DI 图或 Activity 生命周期，就优先使用它，而不是 createAndroidComposeRule<Activity>()；如果你确实想要快速、类似单元测试的运行方式，则通过 Robolectric 运行它（Roborazzi，或使用 @RunWith(AndroidJUnit4) + isIncludeAndroidResources 的 JVM 测试）。设置方法请参阅 references/compose-testing.md。
• 这会将过去大量缓慢的插桩 Espresso 测试覆盖转移到快速、可并行的 JVM 邻近测试中——但前提是独立测试 ViewModel（针对 StateFlow 使用 Turbine/MockK，而不是通过 UI 测试）。如果 Compose 应用只有“同时测试 ViewModel 的插桩 Compose 测试”，那它只是用新工具重现了旧的倒金字塔。
• 截图测试（Compose Preview Screenshot Testing / Paparazzi / Roborazzi）构成一个独立且并行的层，而不是单元测试或插桩行为测试的替代品——它们能捕获行为断言无法发现的视觉回归（间距、重叠、深色模式对比度），但无法说明状态转换是否正确。
• 将 UI Automator 和 Maestro 风格的端到端流程保留给金字塔顶层：少量真正跨应用或覆盖完整技术栈的冒烟测试旅程（引导、结账、深层链接入口），在夜间/发布流水线中运行，而不是作为 PR 门禁。

设备 / API 碎片化策略

• 始终覆盖应用实际支持的最低 API 和当前目标 API——无论市场份额如何，这两项都不可妥协。
• 除这两项外，应按行为风险而非设备流行度确定优先级：更改了权限模型、后台执行限制或存储范围的 API 级别（例如，分区存储、通知运行时权限、前台服务类型声明），值得在引入该变更的 OS 版本上进行专门覆盖，即使该 OS 版本在你的安装用户群中并不常见。
• 任何具体设备/API 市场份额数字都应视为未经验证，除非有你自己的分析数据作为来源（Play Console 自带的设备目录和应用的 Android Vitals）——公开汇总统计数据几个月内就会过时，而且因应用类别和地域而异。不要在测试规划文档中硬编码“X% 的用户使用 API N”；每个规划周期都应从应用自己的 Play Console 信息中心获取最新数据。
• 折叠屏/平板/扩展布局如今本身就是一个独立于 API 级别的碎片化维度——即使 API 覆盖看起来完整，仅测试手机的矩阵也会越来越无法覆盖大屏和折叠屏设备上的真实使用情况。

何时值得投入截图测试

截图测试有实际的设置和维护成本（基准图会过时，字体或渲染器变动会导致误报，每次有意更改 UI 都会带来审核负担）。在以下情况下，这笔投入是值得的：

• 团队频繁发布 UI 更改，以至于人工视觉审核难以跟上（每天有多个 PR 修改共享组件）。
• 应用有设计系统或组件库，一处回归就会影响许多屏幕——截图测试可以低成本地捕获这种连带影响；行为测试则做不到。
• 支持深色模式、大字体缩放或 RTL 布局，而且过去曾出现未被察觉的回归。

对于仍在快速迭代视觉设计的小团队来说，这不是理想的早期投入——有意更新基准图的频率会很高，掩盖真正回归的信号。先使用主机端工具（Compose Preview Screenshot Testing、Paparazzi、Roborazzi）进行低成本迭代；只有在某个对渲染敏感的界面（WebView、Maps、相机预览、自定义 Canvas/GPU 工作）已经导致主机端渲染无法捕获的视觉缺陷并随版本发布后，才添加基于设备的快照测试（Shot，或排除 ATD 的设备运行）。

编写测试

• Espresso（Views）：打开 references/espresso-patterns.md
• Compose：打开 references/compose-testing.md
• UI Automator（系统级或跨应用）：打开 references/uiautomator.md
• 截图测试：打开 references/screenshot-testing.md
• 自适应屏幕尺寸测试：打开 references/adaptive-screen-testing.md
• 无障碍检查：打开 references/accessibility-checks.md

Compose Test v2 迁移

v1 Compose 测试 API（androidx.compose.ui.test.junit4.createComposeRule）已弃用。v2（...junit4.v2.createComposeRule、...test.v2.runComposeUiTest，来自 ui-test-junit4 1.11.0-alpha03+）将默认调度器从 UnconfinedTestDispatcher 切换为 StandardTestDispatcher，并默认强制使用触摸输入模式。标准 UI 断言会自动同步；直接读取状态和手动控制时钟可能需要 waitForIdle()/runOnIdle {} 或推进调度器（分类条目 #1）。完整迁移指南、失败类别说明和代码示例请参阅 references/compose-testing.md。

工作流

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

• 选择能够观察该行为的最精简框架：优先使用 Espresso 或 Compose，在系统边界处使用 UI Automator。
• 添加稳定的选择器：View id、Compose Modifier.testTag、系统 resource-id 或内容描述。
• 控制外部因素：模拟网络、使用确定性数据、固定时间和区域设置，并使用稳定的图像来源。
• 通过框架同步或显式条件添加等待；避免使用 Thread.sleep()。
• 先在本地运行 connectedAndroidTest 或单个托管设备任务，再扩大测试矩阵。

添加截图覆盖

• 对由 @Preview 驱动的 Compose UI 状态使用 Compose Preview Screenshot Testing。
• 需要快速运行 JVM 测试并覆盖 Compose 和旧版 Views 时，使用 Paparazzi 或 Roborazzi。
• 保持基准图精简、易于审核，并对应稳定的 UI 状态，而不是易变内容的整屏快照。
• 在 CI 中为每次失败捕获 HTML 或差异产物。

诊断不稳定的插桩测试

• 先在本地或单台托管设备上复现，再扩大测试矩阵。
• 消除非确定性因素：网络、区域设置、时钟、功能标志、图像加载和渲染器差异。
• 将休眠替换为空闲同步、waitUntil、onElement 或基于监听器的同步。
• 捕获 logcat、屏幕截图、屏幕录制，以及任何托管设备的失败快照。
• 如果仍然不稳定，可通过 Orchestrator 或运行器参数进一步隔离应用状态，并对交互步骤进行二分排查。

添加 CI 门禁（首选：构建托管设备）

• 当不需要硬件渲染且镜像支持相应 API 级别时，配置构建托管设备和 ATD 镜像。
• 如果运行器不支持硬件渲染，请添加 GitHub Actions GPU 标志。
• 让 PR 门禁保持精简且结果确定；在 nightly 和发布流水线中扩展设备组或分片。
• 上传 build/reports/androidTests/ 中的报告、截图报告、差异图像、logcat 和托管设备输出。
• 分别报告构建、安装、启动、交互和分发证据。记录 APK/AAB 标识、变体、设备/API、区域设置、确切的测试任务和产物；Gradle 构建只能证明已打包，只有在指定设备上通过结果断言，才能证明已执行相应流程。
• 在相关真实设备或分发渠道检查运行之前，不要将通知、计费、深层链接、后台工作和 OEM 特定流程标记为已验证。

ADB 命令（排查）

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

# Screen recording
adb shell screenrecord /sdcard/demo.mp4

# Pull managed-device test artifacts after a local failure
adb pull /sdcard/Android/media ./device-artifacts

CI 集成

首选：构建托管设备。请参阅 references/gradle-managed-devices.md 和 references/android-ci-optimization.md。

# .github/workflows/android.yml
name: Android CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6  # or later — verify at actions/checkout releases
      - uses: actions/setup-java@v5  # or later
        with:
          java-version: '21'  # SDK 36 unit tests need JDK 21
          distribution: 'temurin'
      - uses: gradle/actions/setup-gradle@v5  # or later
      - run: ./gradlew testDebugUnitTest <device><api>DebugAndroidTest -Pandroid.testoptions.manageddevices.emulator.gpu=swiftshader_indirect

导航

参考指南有意写得很长；请在其中搜索，而不要一次性加载全部内容：

• rg -n "^## " skills/universal/qa-testing-android/references/compose-testing.md
• rg -n "Idling|waitUntil|Synchronization" skills/universal/qa-testing-android/references/compose-testing.md
• rg -n "DisplaySizeRule|DeviceConfigurationOverride|fold" skills/universal/qa-testing-android/references/adaptive-screen-testing.md
• rg -n "PreviewTest|Paparazzi|Roborazzi|Shot" skills/universal/qa-testing-android/references/screenshot-testing.md

建议 / 避免

建议

• 在稳定的 CI 中优先使用构建托管设备和 ATD 镜像
• 仅在隔离能解决实际状态泄漏或崩溃问题时使用 Android Test Orchestrator
• 为高价值 UI 流程添加截图和无障碍检查
• 在 PR 中运行小规模矩阵，并在 nightly 或发布流水线中通过设备组或分片扩大覆盖范围
• 对每个 ViewModel 和 StateFlow 测试，使用 MainDispatcherRule + TestDispatcher（runTest { }、advanceUntilIdle()、kotlinx-coroutines-test）；只有在有意测试该调度行为时才选择即时执行的 UnconfinedTestDispatcher，因为它可能掩盖顺序竞争问题
• 在 CI 中运行发布变体冒烟测试，每个数据类至少测试一个 @Serializable 端点，以便在发布前发现 R8 全模式剥离 kotlinx-serialization $serializer 类的问题（请参阅 software-android-runtime-debugging/references/proguard-r8-triage.md）
• 对于 Compose 测试，应断言语义状态（onNodeWithTag(...).assertTextEquals(...)），而不是断言 UI 状态对象的引用相等性，因为 Strong Skipping Mode 意味着 UI 在不同发射中可能收到同一个实例，也可能不会

避免

• 使用 Thread.sleep() 进行同步
• 依赖实时后端或对时间敏感的外部内容的测试
• 使用本地化文本或仅按位置定位等不稳定的选择器
• 在需要硬件渲染保真度时，在 ATD 上断言设备级截图
• 断言不同发射间的 StateFlow<UiState> 引用相等（assertThat(state).isSameInstanceAs(previous)）——由 copy() 创建的新 data class 实例引用不同，但结构相等；应测试语义相等性，而非对象标识
• 只在 debug 构建中运行依赖序列化的测试——debug 中不会启用 R8，因此仅运行 debug 套件无法发现序列化 keep 规则问题

资源

资源	用途
references/espresso-patterns.md	Espresso 匹配器和操作
references/compose-testing.md	Compose 测试指南
references/uiautomator.md	用于系统 UI 和基准测试的 UI Automator 模式
references/gradle-managed-devices.md	托管设备配置和 CI
references/screenshot-testing.md	视觉回归测试
references/adaptive-screen-testing.md	屏幕尺寸和折叠设备覆盖
references/accessibility-checks.md	Espresso 和 Compose 的无障碍检查
references/test-orchestrator-patterns.md	AndroidX Test Orchestrator 模式
references/android-ci-optimization.md	CI 流水线优化
references/modern-test-tooling.md	JUnit 5、MockK、Turbine、Robolectric、Maestro
data/sources.json	精选外部来源

模板

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

相关技能

技能	用途
software-mobile	Android 开发
qa-testing-strategy	测试策略
qa-testing-mobile	跨平台移动开发
software-android-native	原生 Android 实现和 Agent 工作流
software-android-runtime-debugging	构建、安装和启动验证，以及过期构建排查
software-android-design	原生 Android 视觉设计和 Material 3 审查

经验总结循环

当先前的决策或问题与当前任务相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史记录或它是唯一可用的备选资料时，才使用 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到了值得记住的模式、值得预防的错误，或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目符号。不要修改 SKILL.md 本身。