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

Compose 預覽螢幕截圖測試

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

螢幕截圖測試是自動測試，可擷取 UI 畫面的螢幕截圖然後與先前核准的參考圖片比較。如果兩張圖像不相符，測試失敗並產生 HTML 報告，協助您進行比較

使用 Compose 預覽螢幕截圖測試工具，您可以：

找出要使用的現有或新的可組合項預覽擷取螢幕截圖測試
從這些可組合項預覽產生參考圖片。
產生 HTML 報表，在您變更程式碼後，這份報表會指出這些預覽畫面的變更。
使用 @Preview 參數 (例如 uiMode 或 fontScale) 和多重預覽來擴大測試規模
使用新的 screenshotTest 來源集模組化測試。

，瞭解如何調查及移除這項存取權。

需求條件

如要使用 Compose 預覽螢幕截圖測試，您需要下列項目：

Android Gradle 8.5.0-beta01 以上版本。
Kotlin 1.9.20 以上版本。

設定

如要啟用這個工具，請按照下列步驟操作：

新增 com.android.compose.screenshot 外掛程式版本 0.0.1-alpha01至您的專案。

將外掛程式新增至版本目錄檔案：

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

在模組層級 build.gradle.kts 檔案中，將外掛程式新增至 plugins {} 區塊：
```
plugins {
    ...
    alias(libs.plugins.screenshot)
}
```

在專案的 gradle.properties 檔案。

android.experimental.enableScreenshotTest=true

在模組層級的 android {} 區塊中 build.gradle.kts 檔案中，啟用實驗性旗標以使用 screenshotTest 來源集，並確認 kotlinCompilerExtensionVersion 設為 1.5.4 以上。
注意：如果您使用 Kotlin 2.0 以上版本，就不需要設定單獨撰寫 Compiler 版本。如想進一步瞭解來電目錄、轉接和錄音服務政策， Compose Compiler Gradle 外掛程式。
```
android {
    ...
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.4"
    }
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```

請確認您已新增 ui-tooling敬上依附元件

將版本新增至版本目錄：

[libraries]
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}

將其新增至模組層級 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。

已知問題

您可以在工具的問題追蹤器元件中，查看目前的已知問題清單。回報其他意見回饋和問題 Issue Tracker。

版本更新

現行版本的版本資訊和異動

0.0.1-alpha06

這個版本提供以下功能：

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

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

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

修正錯誤：部分 Compose 轉譯器錯誤，現已支援空白撰寫
效能強化：更新圖片差異演算法，以提升速度