Compose 预览屏幕截图测试

屏幕截图测试可以有效验证界面对用户的显示效果。通过 Compose 预览屏幕截图测试工具结合了 可组合项预览,其中包含 运行主机端屏幕截图测试后工作效率的提升。Compose 预览 屏幕截图测试旨在像可组合项预览一样易于使用。

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

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

  • 确定要用于哪些现有或新的可组合项预览 屏幕截图测试。
  • 根据这些可组合项预览生成参考图片。
  • 生成 HTML 报告,以识别预览后发生的更改 更改代码
  • 使用 @Preview 参数(例如 uiModefontScale)和多预览 以帮助您扩展测试
  • 使用新的 screenshotTest 源代码集将测试模块化。
。 <ph type="x-smartling-placeholder">
</ph>
图 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. 在模块级的 android {} 代码块中 build.gradle.kts 文件,请启用实验性标志以使用 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)

验证任务会在以下位置创建 HTML 报告: {module}/build/reports/screenshotTest/preview/{variant}/index.html

已知问题

您可以在该工具的 问题跟踪器组件。报告任何其他反馈和问题 (通过问题跟踪器)。

版本更新

当前版本的版本说明和变更

0.0.1-alpha06

此版本引入了以下功能:

图片差异阈值:借助新的全局阈值设置,您可以 可以更好地控制屏幕截图比较如需进行配置,请更新您的 模块的 build.gradle.kts:

android {
    ...
    testOptions {
        ...
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

此阈值将应用于模块中定义的所有屏幕截图测试。

  • bug 修复:一些 Compose Renderer bug,并添加了对空 Compose 的支持
  • 性能增强功能:更新了图片差异算法,提升了速度