Compose 預覽螢幕截圖測試

螢幕截圖測試可有效驗證使用者看到的使用者介面外觀。Compose 預覽螢幕截圖測試工具結合可組合預覽的簡易性和功能，以及執行主機端螢幕截圖測試的效率提升。Compose 預覽螢幕截圖測試旨在讓您輕鬆使用可組合項預覽。

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

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

• 找出要用於螢幕截圖測試的現有多個現有或新的可組合項預覽。
• 透過這些可組合項預覽產生參考圖片。
• 產生 HTML 報表，用於識別您在變更程式碼後所做的變更。
• 使用 @Preview 參數 (例如 uiMode 或 fontScale) 和多重預覽，協助調整測試規模。
• 使用新的 screenshotTest 來源集將測試模組化。

相關規定

如要使用 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 中的預覽共用其完整方法名稱，則主要位於主要內的預覽會誤用於測試，而不是螢幕截圖測試。