此页面由 Cloud Translation API 翻译。

Compose 预览屏幕截图测试
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

屏幕截图测试是一种有效的方式，可验证界面在用户眼中的呈现效果。Compose 预览屏幕截图测试工具将可组合项预览的简单性和功能与运行主机端屏幕截图测试的效率提升相结合。Compose 预览屏幕截图测试的使用方式与可组合项预览一样简单。

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

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

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

要求

如需使用 Compose 预览屏幕截图测试，您需要满足以下条件：

Android Gradle 插件 8.5.0-beta01 或更高版本。
Kotlin 1.9.20 或更高版本。我们建议使用 Kotlin 2.0 或更高版本，以便使用 Compose 编译器 Gradle 插件。
为您的项目启用 Compose。我们建议您使用 Compose 编译器 Gradle 插件启用 Compose。

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

设置

如需启用该工具，请按以下步骤操作：

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

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

[versions]
agp = "8.11.0-alpha06"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha10"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

在模块级 build.gradle.kts 文件中，在 plugins {} 代码块中添加该插件：
```
plugins {
    alias(libs.plugins.screenshot)
}
```

在项目的 gradle.properties 文件中启用实验性属性。
```
android.experimental.enableScreenshotTest=true
```
在模块级 build.gradle.kts 文件的 android {} 块中，启用实验性标志以使用 screenshotTest 源代码集。
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```

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

将其添加到版本目录中：

[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"}

将它们添加到模块级 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!")
    }
}

生成参考图片

设置测试类后，您需要为每个预览生成参考图片。这些参考图片用于在您进行代码更改后识别更改。如需为可组合项预览屏幕截图测试生成参考图片，请运行以下 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) 中找到参考图片。

生成测试报告

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

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 报告。

已知问题

您可以在该工具的问题跟踪器组件中查看已知问题的最新列表。如有任何其他反馈和问题，请通过问题跟踪器报告。

版本更新

持续版本的版本说明和变更。

0.0.1-alpha10

此版本引入了以下功能：

从此版本开始，您需要使用 @PreviewTest 注解标记所有预览函数。系统不会执行不带注解的预览。
参照图片目录已从 {module}/src/{variant}/screenshotTest/reference 更改为 {module}/src/screenshotTest{Variant}/reference。这是为了确保这些生成的参考映像不会成为正式版代码的一部分，并与其他测试类型的目录结构保持一致。
{variant}PreviewScreenshotRender 任务已移除。图片渲染已迁移到 JUnit 测试引擎。
update{Variant}ScreenshotTest 任务会先将新的渲染图片与参考图片进行比较，然后再进行更新。它只会更新差异大于指定阈值的图片。移除了 --updateFilter 命令行标志。

0.0.1-alpha06