Compose 預覽螢幕截圖測試

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

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

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

  • 找出要用於螢幕截圖測試的現有或新可組合函式預覽畫面數量。
  • 根據這些可組合函式預覽畫面產生參考圖片。
  • 產生 HTML 報表,在您變更程式碼後,這份報表會指出這些預覽畫面的變更。
  • 使用 @Preview 參數 (例如 uiModefontScale) 和多重預覽功能,有助於擴大測試範圍。
  • 使用新的 screenshotTest 來源集,將測試模組化。
圖 1. HTML 報告範例。

需求條件

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

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

設定

如要啟用這項工具,請按照下列步驟操作:

  1. com.android.compose.screenshot 外掛程式 0.0.1-alpha07 版本新增至專案。
    1. 將外掛程式新增至版本目錄檔案:
      [versions]
      agp = "8.5.0-beta01"
      kotlin = "1.9.20"
      ...
      screenshot = "0.0.1-alpha07"
      
      [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 報表。

已知問題

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

版本更新

持續性版本的版本資訊和變更

0.0.1-alpha06

這次發布中推出了以下功能:

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

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

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

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