Compose 预览屏幕截图测试

屏幕截图测试是验证界面外观的有效方式。Compose 预览屏幕截图测试工具将可组合预览的简易性和功能与运行主机端屏幕截图测试的效率结合在一起。Compose 预览屏幕截图测试旨在与可组合项预览一样易于使用。

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

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

  • 确定您要用于屏幕截图测试的一些现有或新的可组合项预览。
  • 根据这些可组合项预览生成参考图片。
  • 更改代码后，生成 HTML 报告以标识这些预览的更改。
  • 使用 @Preview 参数（例如 uiMode 或 fontScale）和多次预览可帮助您扩展测试。
  • 使用新的 screenshotTest 源代码集将您的测试模块化。
图 1.HTML 报告示例。

要求

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

  • Android Gradle 8.5.0-beta01 或更高版本。
  • Kotlin 1.9.20 或更高版本。

设置

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

  1. 将 com.android.compose.screenshot 插件（版本 0.0.1-alpha01）添加到您的项目中。
    1. 将该插件添加到您的版本目录文件中： 
      [versions]
agp = "8.5.0-beta01"
kotlin = "1.9.20"
...
screenshot = "0.0.1-alpha01"

[plugins]
...
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
    2. 在模块级 build.gradle.kts 文件中，将该插件添加到 plugins {} 代码块中： 
      plugins {
    ...
    alias(libs.plugins.screenshot)
}
  2. 在项目的 gradle.properties 文件中启用实验性属性。 
    android.experimental.enableScreenshotTest=true
  3. 在模块级 build.gradle.kts 文件的 android {} 代码块中，启用实验性标志以使用 screenshotTest 源代码集，并确保将 kotlinCompilerExtensionVersion 设置为 1.5.4 或更高版本。 
    android {
    ...
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.4"
    }
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
  4. 确保您已添加 ui-tooling 依赖项。
    1. 请将其添加到版本目录中： 
      [libraries]
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
    2. 将它添加到您的模块级 build.gradle.kts 文件中： 
      dependencies {
  screenshotTestImplementation(libs.androidx.compose.ui.tooling)
}

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

如需指定要用于屏幕截图测试的可组合项预览，请将预览放在测试类中。测试类文件必须位于新的 screenshotTest 源代码集中，例如 app/src/screenshotTest/kotlin/com/google/yourapp/ExamplePreviewScreenshots.kt ({module}/src/screenshotTest/{kotlin|java}/com/your/package)。

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

package com.google.yourapp

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.google.yourapp.ui.theme.MyApplicationTheme

class ExamplePreviewsScreenshots {

    @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/debug/screenshotTest/reference ({module}/src/{variant}/screenshotTest/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 报告。

已知问题

  • 如果 screenshotTest 源代码集中的预览与 main 中的预览共用其完全限定方法名称，则 main 中的预览会错误地用于测试，而不是屏幕截图测试。