本頁面由 Cloud Translation API 翻譯而成。

Compose 預覽螢幕截圖測試

螢幕截圖測試是驗證使用者看到的 UI 外觀的有效方法。Compose 預覽螢幕截圖測試工具結合了可組合項預覽畫面的簡易性和功能，以及執行主機端螢幕截圖測試的生產力提升。Compose 預覽螢幕截圖測試功能的設計，是為了讓使用者能像使用可組合函式預覽畫面一樣輕鬆操作。

螢幕截圖測試是一種自動化測試，會擷取 UI 的螢幕截圖，然後與先前核准的參考圖片進行比較。如果圖片不相符，測試就會失敗，並產生 HTML 報表，協助您比較並找出差異。

您可以使用 Compose 預覽螢幕截圖測試工具執行以下操作：

使用 @PreviewTest 為現有或新的可組合項預覽畫面建立螢幕截圖測試。
從這些可組合函式預覽畫面產生參考圖片。
產生 HTML 報表，在您變更程式碼後，這份報表會指出這些預覽畫面的變更。
使用 @Preview 參數 (例如 uiMode 或 fontScale) 和多重預覽功能，有助於擴大測試範圍。
使用新的 screenshotTest 來源集，將測試模組化。

需求條件

如要使用 Compose 預覽螢幕截圖測試功能，您需要：

Android Gradle 外掛程式 8.5.0-beta01 以上版本。
Kotlin 1.9.20 以上版本。建議您使用 Kotlin 2.0 以上版本，以便使用 Compose Compiler Gradle 外掛程式。
專案已啟用 Compose。建議您使用 Compose Compiler 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

本版本推出了以下功能：

圖片差異門檻：這項新的全域門檻設定可讓您更精確地控制螢幕截圖比較結果。如要設定，請更新模組的 build.gradle.kts：

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

這個門檻會套用至模組中定義的所有螢幕截圖測試。

修正錯誤：修正部分 Compose 轉譯器錯誤，並新增對空白 Compose 的支援
效能提升：更新圖片差異比較演算法，以便加快速度