Compose 预览屏幕截图测试

实验性功能： Compose 预览版屏幕截图测试仍在开发中。在 Alpha 阶段，其功能和 API 可能会发生重大变化。 请通过问题跟踪器报告任何反馈和问题。

屏幕截图测试是一种有效的方法，可用于验证界面在用户眼中的外观。 Compose 预览版屏幕截图测试工具兼具 可组合项预览的简洁性和功能，同时还能通过运行主机端屏幕截图测试来提高工作效率。Compose 预览版屏幕截图测试旨在实现与可组合函数预览一样简单易用的效果。

屏幕截图测试是一种自动化测试，用于截取部分界面元素的屏幕截图，然后将其与之前批准的参考图片进行比较。如果图片不匹配，测试会失败并生成 HTML 报告，帮助您比较并找出差异。

借助 Compose 预览版屏幕截图测试工具，您可以：

• 使用 @PreviewTest 为现有或新的可组合预览创建屏幕截图测试。
• 根据这些可组合项预览生成参考图片。
• 生成 HTML 报告，用于在您更改代码后识别这些预览的更改。
• 使用 @Preview 参数（例如 uiMode 或 fontScale）和多重预览来帮助您扩大测试规模。
• 使用新的 screenshotTest 源代码集将测试模块化。

图 1：HTML 报告示例。

IDE 集成

虽然您可以通过手动运行底层 Gradle 任务（updateScreenshotTest 和 validateScreenshotTest）来使用 Compose 预览屏幕截图测试工具，但 Android Studio Otter 3 功能更新 Canary 4 引入了完整的 IDE 集成。这样，您就可以完全在 IDE 中生成参考图片、运行测试和分析验证失败情况。以下是一些主要功能：

• 编辑器中的边线图标。您现在可以直接从源代码运行测试或更新参考图片。在带有 @PreviewTest 注释的可组合函数和类旁边的边线中，会显示绿色的运行图标。
  • 运行屏幕截图测试。专门针对单个函数或整个类执行测试。
  • 添加或更新参考图片。专门针对所选范围触发更新流程。

• 互动式参考管理。更新参考图片现在更安全、更精细。
  • 新的参考图片生成对话框。现在，您无需运行批量 Gradle 任务，只需通过新对话框直观地选择要生成或更新哪些预览即可。
  • 预览变体。该对话框会单独列出所有预览变体（例如浅色主题或深色主题，或不同的设备），让您可以在生成图片之前选择或取消选择特定项。

• 集成的测试结果和差异比较查看器。无需离开 IDE 即可查看结果。
  • 统一的运行面板。屏幕截图测试结果显示在标准的 Run 工具窗口中。测试按类和函数分组，并清楚标记通过或失败状态。
  • 视觉差异工具。如果测试失败，您可以在屏幕截图标签页中并排比较参考、实际和差异图片。
  • 详细属性。属性标签页提供有关失败测试的元数据，包括匹配百分比、图片尺寸和所用的具体预览配置（例如 uiMode 或 fontScale）。

• 灵活的测试范围界定。现在，您可以直接从“项目”视图中执行各种范围的屏幕截图测试。右键点击模块、目录、文件或类，即可专门针对所选内容运行屏幕截图测试。

要求

如需通过完整的 IDE 集成使用 Compose 预览版屏幕截图测试，您的项目必须满足以下要求：

• Android Studio Panda 1 Canary 4 或更高版本。
• Android Gradle 插件 (AGP) 版本 9.0 或更高版本。
• Compose 预览版屏幕截图测试插件版本 0.0.1-alpha15 或更高版本。
• Kotlin 版本 2.2.10 或更高版本。
• JDK 版本 17 或更高版本。
• 已为您的项目启用 Compose。我们建议使用 Compose 编译器 Gradle 插件启用 Compose。

如果您只想使用底层 Gradle 任务，而无需 IDE 集成，则需要满足以下要求：

• Android Gradle 插件 (AGP) 版本 8.5.0 或更高版本。
• Compose 预览版屏幕截图测试插件版本 0.0.1-alpha15 或更高版本。
• Kotlin 版本 1.9.20 或更高版本。我们建议使用 Kotlin 2.0 或更高版本，以便您可以使用 Compose 编译器 Gradle 插件。
• JDK 版本 17 或更高版本。
• 已为您的项目启用 Compose。我们建议使用 Compose 编译器 Gradle 插件启用 Compose。

注意： 如果您无法使用 Compose 编译器 Gradle 插件，可以通过直接声明对 Compose 编译器的依赖项来启用 Compose。 确保您使用的是 kotlinCompilerExtensionVersion 1.5.4 版或更高版本。

设置

集成式工具和底层 Gradle 任务都依赖于 Compose 预览版屏幕截图测试插件。要设置插件，请按以下步骤操作：

1. 在项目的 gradle.properties 文件中启用实验性属性。

   android.experimental.enableScreenshotTest=true
   

2. 在模块级 build.gradle.kts 文件的 android {} 块中，启用实验性标志以使用 screenshotTest 源代码集。

   android {
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

3. 将 com.android.compose.screenshot 插件（版本 0.0.1-alpha15）添加到您的项目中。

   1. 将插件添加到版本目录文件中：

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha15"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

   2. 在模块级 build.gradle.kts 文件中，在 plugins {} 代码块中添加插件：

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. 添加 screenshot-validation-api 和 ui-tooling 依赖项。

   1. 将它们添加到您的版本目录中：

      [libraries]
      screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
      androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
      

   2. 将它们添加到模块级 build.gradle.kts 文件中：

      dependencies {
        screenshotTestImplementation(libs.screenshot.validation.api)
        screenshotTestImplementation(libs.androidx.ui.tooling)
      }
      

指定用于屏幕截图测试的可组合项预览

如需指定要用于屏幕截图测试的可组合项预览，请使用 @PreviewTest 注解标记预览。预览必须位于新的 screenshotTest 源代码集，例如：

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

您可以在此文件或在同一源代码集中创建的其他文件中添加更多可组合项或预览（包括多重预览）。

package com.example.yourapp

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.yourapp.ui.theme.MyApplicationTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyApplicationTheme {
        Greeting("Android!")
    }
}

生成参考图片

设置测试类后，您需要为每个预览生成参考图片。这些参考图片用于在您进行代码更改后识别后续更改。如需为可组合函数预览版屏幕截图测试生成参考图片，请按照本部分中的说明操作，以了解 IDE 集成或 Gradle 任务。

在 IDE 中

点击 @PreviewTest 函数旁边的边线图标，然后选择 Add/Update Reference Images。在对话框中选择预览，然后点击添加。

使用 Gradle 任务

运行以下 Gradle 任务：

• Linux 和 macOS：./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
• Windows：gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

任务完成后，在 app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference) 中查找参考图片。

注意： 参考图片的命名方式是将测试函数的完全限定名称与预览参数的哈希值串联起来，例如 com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png。

生成测试报告

参考图片存在后，请按照本部分中针对 IDE 集成或 Gradle 任务的说明生成测试报告。

在 IDE 中

点击 @PreviewTest 函数旁边的边线图标，然后选择 Run 'ScreenshotTests'。

如果测试失败，请点击运行面板中的测试名称。选择屏幕截图标签页，使用集成的缩放和平移控件检查图片差异。

注意： 重命名带有 @PreviewTest 注解的函数会破坏与现有参考图片的关联。在这种情况下，您必须为新函数名称重新生成参考图片。

使用 Gradle 任务

运行验证任务以拍摄新的屏幕截图，并将其与参考图片进行比较：

• Linux 和 macOS：./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
• Windows：gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

验证任务会在 {module}/build/reports/screenshotTest/preview/{variant}/index.html 中创建 HTML 报告。

问题排查

Compose 预览版屏幕截图测试运行的是主机端测试，可能会占用大量内存。您可以通过向 gradle.properties 文件添加以下属性来增加测试 JVM 的最大堆大小：

android.compose.screenshot.maxHeapSize=4g

已知问题

• Kotlin Multiplatform (KMP)：IDE 和底层插件均专为 Android 项目而设计。它们不支持 KMP 项目中的非 Android 目标平台。

您可以在该工具的问题跟踪器组件中找到当前已知问题的完整列表。如需报告任何其他反馈和问题，请使用问题跟踪器。

版本更新

如需查看完整的版本更新列表，请参阅版本说明。