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 工具窗口中。测试按类和函数分组，并清楚地标记通过或失败状态。
  • 可视化差异工具。当测试失败时，您可以在 Screenshot 标签页中并排比较 Reference、 Actual 和 Diff 图片。
  • 详细属性。Attributes 标签页提供有关失败测试的元数据，包括匹配百分比、图片尺寸和所用的特定预览配置（例如 uiMode 或 fontScale）。

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

要求

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

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

如果您只想使用底层 Gradle 任务而不使用 IDE 集成，则要求如下：

• Android Gradle 插件 (AGP) 8.5.0 或更高版本。
• Compose 预览屏幕截图测试插件版本 0.0.1-alpha14 或更高版本。
• 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-alpha14）添加到您的项目中。

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha14"
      
      [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 。在对话框中选择预览，然后点击 Add 。

使用 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' 。

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

注意： 重命名使用 @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 报告。

已知问题

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

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

版本更新

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