testing-setup

步骤 1：分析当前测试配置

要了解现有项目的测试配置，请在 libs.versions.toml 文件或构建文件中查找以下依赖项：

1. 使用的依赖注入框架。例如，Hilt、Koin、Anvil 或原生 Dagger。
2. 项目使用的单元（本地）测试框架。例如，JUnit4 或 JUnit5。
3. 单元测试以及插桩测试和 UI 测试所使用的模拟框架（如果有）。例如，Mockito 或 Mockk。
4. Robolectric。确定以下三种用途中适用的用途：
   1. 在单元测试中为平台实体提供伪对象
   2. 在没有设备或模拟器的情况下运行行为 UI 测试。例如，用于运行 Espresso 或 Compose 测试。
   3. 使用 Roborazzi 进行截图测试
5. 应用是完全基于 Compose、Views，还是混合架构？
6. 行为 UI 测试：
   1. Compose 测试（androidx.compose.ui:ui-test-*）
   2. Views 的 Espresso 测试。检查是否使用 Kaspresso 等包装库。依赖项：androidx.test.espresso:espresso-core、androidx.test:runner、androidx.test:rules。
7. 截图测试。确定项目使用以下哪种类型：
   1. 插桩测试（基于设备）。例如，使用 Dropshots。
   2. 基于 Robolectric，因此可在本地运行。例如，使用 Roborazzi。
   3. 基于 LayoutLib，因此可在本地运行。例如，Paparazzi 或 Compose Preview Screenshot Testing 工具。
8. 端到端测试（也称为候选发布版本测试）始终在设备上运行，并使用 UIAutomator、Appium 或 Robotium 等高级框架。
9. 生成包含分析结果的 Markdown 报告

步骤 2：为测试配置依赖注入框架

如果项目尚未使用依赖注入框架，请安装一个：如果是多平台应用，请询问用户是否要安装 Koin 或 kotlin-inject。如果不是多平台应用，请安装 Hilt。

安装测试依赖项（例如 com.google.dagger:hilt-compiler，应使用 kspAndroidTest 配置）。

重要

**重要：**始终查阅适用框架的文档，了解如何进行测试（例如：Hilt 测试指南、Koin 插桩测试）。

对于插桩测试，请创建并配置新的测试运行器（在构建 Gradle 文件中添加 testInstrumentationRunner），并应用框架要求的测试规则（例如，在 Hilt 中，使用 @HiltAndroidTest 注解测试类，并应用 HiltAndroidRule）。其他框架使用不同的机制，请查阅其文档。

第 3 步：安装框架

除非另有说明，否则请遵循当前使用的测试框架。

如果没有测试框架，且用户未指定偏好，请安装以下框架：

• 用于本地测试和插桩测试的 JUnit4

• 用于测试覆盖率的 JaCoCo

• UI 测试：如果项目使用 Views，则使用 Espresso；如果完全使用 Compose，则使用 Compose Testing API。

• 使用 Robolectric 运行 UI 测试

• 用于截图测试的 Compose Preview Screenshot Testing 工具。先检查项目的 AGP 版本，再选择匹配的配置并严格遵循：

  • **AGP 9.5.0-alpha03 或更高版本（推荐）：**按 使用测试套件进行截图测试 中的说明，通过 testOptions { screenshotTests.create(...) } 配置 AGP 测试套件。
  • **更低版本的 AGP：**使用 旧版独立插件配置 和 com.android.compose.screenshot，并告知用户此配置已弃用。不要为了配置截图测试而升级 AGP。说明 9.5.0-alpha03 或更高版本支持测试套件，并将是否升级留作单独决定。

  不要在同一模块中同时使用这两种配置。如果项目已使用独立插件，且其 AGP 版本支持测试套件，请根据使用测试套件进行截图测试中的任务和路径映射表，提出迁移建议。

• 用于设备截图测试的 Dropshots

• 如果确实需要模拟框架，请安装 Mockk（io.mockk:mockk）。除非明确必要，否则不要安装。

如果用户要求插桩截图测试，请安装 Dropshots。

如果用户要求端到端测试，请安装 UI Automator。

第 4 步：重构并创建测试替身

为单元测试进行重构

接下来的部分会要求你创建测试。如果你依赖 Android 框架类或代码库中不存在的实体：

• 首先使用测试替身。如果不存在，则为该类创建接口，并使用现有代码提供一个 “Default” 实现。将 Fake 版本添加到测试源集（test 或 androidTest）。

• 如果无法使用测试替身（例如，无法访问该类或接口），则模拟这些依赖项。

为 UI 测试进行重构

如果需要用测试替身替换组件，以便让测试更简单、更快速、更可靠，请用测试替身替换速度慢且有问题的依赖项。使用已安装的依赖注入框架实现运行时测试替身，以便：

• 模拟用户的不同场景（凭据错误或密码重置流程）、服务器的不同场景（无连接、服务器宕机或服务器返回错误的 JSON），或平台组件的不同场景（权限不足、磁盘空间不足或没有可用的前置摄像头）
• 提升速度和可靠性（将数据库替换为内存数据库，或将仓库替换为内存测试替身，避免访问网络）

第 5 步：单元测试

创建任务，为每个包含业务逻辑的文件添加或审查单元测试（ViewModels、Repositories，以及 DAO 等数据库相关类）。不要为 Activity、Compose 布局或依赖注入配置文件创建单元测试。

第 6 步：UI 测试

Espresso 或 Compose UI 测试位于 test 源集，因为它们将通过 Robolectric 运行。如果要求进行插桩测试（模拟器或设备），请将其放入 androidTest 源集。

第 7 步：测试数据库

如果数据库使用 SQLite（通过 Room 或 SQLDelight 等库），请使用内存数据库创建插桩测试，确保数据库能在设备上与 SQLite 引擎正常配合。

步骤 8：截图测试

无论使用哪种框架，截图测试都侧重于以下两类测试：

• 屏幕级截图测试：以九种不同尺寸测试每个屏幕，将紧凑、中等和展开宽度（400、610、900 dp）与高度（400、500 和 1000 dp）组合起来。
• 屏幕级变体。添加以下内容的移动设备（400x500）截图：
  • 所有备用主题（如果使用）。
  • 字体缩放设为 1.5。
• 组件级截图测试：以不同主题和字体缩放测试每个组件。

截图不会测试行为，但如果界面会因状态而发生较大变化，也要测试不同的常见场景。例如，可以通过向界面注入加载状态或使用假对象模拟加载状态，来测试加载屏幕。

步骤 9：UI 行为测试

使用行为测试验证 UI 逻辑，确保在传入不同状态以及执行用户操作时，UI 都能按预期响应。

Compose UI 行为测试

• 使用 ComposeTestRule 和 ComponentActivity 访问字符串等资源。
• 始终优先使用语义匹配器进行匹配。如果匹配器过于复杂，难以编写（查找单个元素时使用了三个以上的匹配器），则使用 testTag。
• 始终验证状态恢复。

Views（XML）UI 行为测试

使用 Espresso 匹配视图并与其交互。

步骤 10：导航测试

创建测试套件以验证导航逻辑。包括：

• 返回操作处理
• Deeplinks
• “通过主页退出”等特殊模式（使用多个返回栈）。

步骤 11：模拟不同的窗口尺寸和设置

对于 Compose 布局，使用 “UI testing common patterns” 中介绍的 DeviceConfigurationOverride，模拟不同的窗口尺寸、字体缩放

步骤 12：端到端测试

创建少量端到端测试（约占所有测试的 5%），覆盖重要的用户流程。使用 Compose Test API 或 Espresso 进行测试。如果需要访问通知或系统 UI 等平台功能，请使用 UI Automator。

如果需要截取设备上运行的应用的屏幕截图，请使用 Dropshots。验证与系统 UI 交互（例如：全面屏渲染、通知、画中画）时，截图测试需要使用设备。

步骤 13：插桩截图测试

在模块中安装 com.dropbox.dropshots 插件和 Dropshots() JUnit Rule。为应用的一项功能创建新的插桩截图测试。

步骤 14：安装 JaCoCo

安装 JaCoCo，以便在本地测试代码覆盖率。

• 在每个包含测试的模块中添加 jacoco 插件。

最后完善

• 询问是否要记录分析结果以及对测试策略所做的更改。如果用户同意：

  • 如果项目中存在 AGENTS.md 文件，请更新该文件，记录对测试策略所做的任何更改。

  • 如果不存在 AGENTS.md 文件，请创建新文件（docs/testing.md），说明测试策略，包括运行每种类型测试所需的命令，以及截图参考文件的存放位置。还要在根目录中创建新的 AGENTS.md 文件，并添加指向 docs/testing.md 的链接。