Compose 预览屏幕截图测试

注意 ：本页面中介绍的独立 com.android.compose.screenshot 插件已不再维护。我们建议使用 Android Gradle 插件 (AGP) 9.5 或更高版本，通过 AGP 测试套件设置屏幕截图测试。如需切换，请参阅迁移现有项目。

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

Android skills

在 GitHub 上查看

创建屏幕截图测试

使用 testing-setup Android 技能制定测试策略并创建屏幕截图测试。

如需从 Android CLI 安装技能，请运行以下命令：

android skills add testing-setup

屏幕截图测试是一种自动化测试，它会截取一段界面的屏幕截图，然后将其与之前批准的参考图片进行比较。如果图片不匹配，测试会失败并生成 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 即可查看结果。
  • 统一的运行面板。屏幕截图测试结果会显示在标准运行工具窗口中。测试按类和函数分组，并清楚地标明通过或失败状态。
  • 视觉差异工具。当测试失败时，您可以在屏幕截图标签页中并排比较参考、实际和差异图片。
  • 详细属性。属性标签页提供有关失败测试的元数据，包括匹配百分比、图片尺寸和所用的特定预览配置（例如 uiMode 或 fontScale）。

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

要求

注意： 如需了解 AGP 测试套件的要求和设置说明，请参阅 AGP 测试套件。

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

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

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

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

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.2.10"
      screenshot = "0.0.1-alpha16"
      
      [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 任务的说明操作。

Android CLI

下载 Android CLI

尝试使用 Android CLI 渲染 Compose 预览

如果您不使用 Android Studio，或者更喜欢通过命令行执行操作，请尝试使用 Android CLI。

例如，当您需要渲染 Compose 预览以进行视觉测试时，请使用 android studio render-compose-preview 命令。

android studio render-compose-preview

在 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'。

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

注意： 重命名带有 @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 目标。

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

版本更新

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