Compose 預覽螢幕截圖測試

注意： 本頁所述的獨立 com.android.compose.screenshot 外掛程式已不再維護。建議您使用 Android Gradle 外掛程式 (AGP) 9.5 以上版本，透過 AGP 測試套件設定螢幕截圖測試。如要切換，請參閱「遷移現有專案」。

螢幕截圖測試是有效的方法，可驗證使用者看到的 UI 樣貌。Compose 預覽螢幕截圖測試工具結合了可組合項預覽的簡易性和功能，以及執行主機端螢幕截圖測試的效率提升。Compose 預覽螢幕截圖測試的使用方式與可組合函式預覽一樣簡單。

Android 技能

前往 GitHub 查看

建立螢幕截圖測試

使用 testing-setup Android 技能制定測試策略，並建立螢幕截圖測試。

如要透過 Android CLI 安裝技能，請執行：

android skills add testing-setup

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

Compose 預覽螢幕截圖測試工具可讓您：

• 使用 @PreviewTest 為現有或新的可組合項預覽畫面建立螢幕截圖測試。
• 從這些可組合項預覽畫面生成參考圖像。
• 在您變更程式碼後，產生 HTML 報表，找出這些預覽畫面的變更。
• 使用 @Preview 參數 (例如 uiMode 或 fontScale) 和多重預覽，協助您擴充測試。
• 使用新的 screenshotTest 來源集，將測試模組化。

圖 1. HTML 報表範例。

IDE 整合

雖然您可以手動執行基礎 Gradle 工作 (updateScreenshotTest 和 validateScreenshotTest)，使用 Compose 預覽螢幕截圖測試工具，但 Android Studio Otter 3 Feature Drop Canary 4 導入了完整的 IDE 整合功能。這樣一來，您就能在 IDE 中生成參考圖像、執行測試，以及分析驗證失敗的原因。以下列舉幾項主要功能：

• 編輯器內溝槽圖示。現在可以直接從原始碼執行測試或更新參考圖像。綠色執行圖示會顯示在可組合函式和以 @PreviewTest 註解的類別旁的邊線中。
  • 執行螢幕截圖測試。專門針對單一函式或整個類別執行測試。
  • 新增或更新參考圖像。針對所選範圍觸發更新流程。

• 互動式參考資料管理。現在更新參考圖像更安全，也更精細。
  • 「New reference image generation」(生成新參考圖像) 對話方塊。您不必執行大量 Gradle 工作，而是可以透過新的對話方塊，以視覺化方式準確選取要產生或更新的預覽畫面。
  • 預覽變化版本。對話方塊會個別列出所有預覽變化版本 (例如淺色主題或深色主題，或不同裝置)，讓您在生成圖像前選取或清除特定項目。

• 整合測試結果和差異檢視器。不必離開 IDE 即可查看結果。
  • 整合執行面板：螢幕截圖測試結果會顯示在標準「Run」工具視窗中。測試會依類別和函式分組，並清楚標示通過或失敗狀態。
  • 視覺化差異工具。測試失敗時，您可以在「Screenshot」分頁中並排比較「Reference」、「Actual」和「Diff」圖片。
  • 詳細屬性。「Attributes」分頁會提供失敗測試的中繼資料，包括相符百分比、圖片尺寸，以及使用的特定預覽設定 (例如 uiMode 或 fontScale)。

• 彈性測試範圍。現在，您可以直接從「Project View」執行各種範圍的螢幕截圖測試。在模組、目錄、檔案或類別上按一下滑鼠右鍵，即可專門針對該選取項目執行螢幕截圖測試。

需求條件

注意： 如需 AGP 測試套件的需求條件和設定操作說明，請參閱「AGP 測試套件」。

如要透過完整的 IDE 整合功能使用 Compose 預覽螢幕截圖測試，專案必須符合下列需求：

• Android Studio Panda 1 Canary 4 以上版本。
• Android Gradle 外掛程式 (AGP) 9.0 以上版本。
• Compose 預覽螢幕截圖測試外掛程式 0.0.1-alpha16 以上版本。
• Kotlin 2.2.10 以上版本。
• JDK 17 以上版本。
• 專案已啟用 Compose。建議使用 Compose Compiler Gradle 外掛程式啟用 Compose。

如果只想使用基礎 Gradle 工作，而不使用 IDE 整合，則須符合以下條件：

• Android Gradle 外掛程式 (AGP) 8.5.0 以上版本。
• Compose 預覽螢幕截圖測試外掛程式 0.0.1-alpha16 以上版本。
• Kotlin 1.9.20 以上版本。建議使用 Kotlin 2.0 以上版本，以便使用 Compose Compiler Gradle 外掛程式。
• JDK 17 以上版本。
• 專案已啟用 Compose。建議使用 Compose Compiler Gradle 外掛程式啟用 Compose。

注意： 如果無法使用 Compose Compiler Gradle 外掛程式，可以直接宣告 Compose Compiler 依附元件，藉此啟用 Compose。請務必使用 kotlinCompilerExtensionVersion 1.5.4 以上版本。

設定

整合式工具和基礎 Gradle 工作都仰賴 Compose 預覽螢幕截圖測試外掛程式。設定外掛程式的步驟如下：

1. 在專案的 gradle.properties 檔案中啟用實驗性屬性。

   android.experimental.enableScreenshotTest=true
   

2. 在模組層級 build.gradle.kts 檔案的 android {} 區塊中，啟用實驗性旗標，以便使用 screenshotTest 來源集。

   android {
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

3. 將 com.android.compose.screenshot 外掛程式 0.0.1-alpha16 版本新增至專案。

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.2.10"
      screenshot = "0.0.1-alpha16"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

   2. 在模組層級 build.gradle.kts 檔案中，將外掛程式新增至 plugins {} 區塊：

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. 新增 screenshot-validation-api 和 ui-tooling 依附元件。

   1. 將這些項目新增至版本目錄：

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

   2. 請將這些依附元件新增至模組層級 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!")
    }
}

生成參考圖像

設定測試類別後，您需要為每個預覽畫面產生參考圖像。這些參考圖像可用於在您變更程式碼後，識別變更。如要為可組合項預覽螢幕截圖測試產生參考圖像，請按照本節的操作說明，整合 IDE 或執行 Gradle 工作。

Android CLI

下載 Android CLI

試用 Android CLI 算繪 Compose 預覽畫面

如果您不使用 Android Studio，或偏好透過指令列執行操作，請試用 Android CLI。

舉例來說，如需轉譯 Compose 預覽畫面進行視覺測試，請使用 android studio render-compose-preview 指令。

android studio render-compose-preview

在 IDE 中

按一下 @PreviewTest 函式旁的空白邊圖示，然後選取「Add/Update Reference Images」。在對話方塊中選取預覽畫面，然後按一下「新增」。

使用 Gradle 工作

執行下列 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) 中尋找參考圖像。

附註： 參考圖像的名稱是由測試函式的完整名稱和預覽參數的雜湊串連而成，例如 com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png。

產生測試報告

參考圖像建立完成後，請按照本節中有關 IDE 整合或 Gradle 工作的操作說明，產生測試報告。

在 IDE 中

按一下 @PreviewTest 函式旁的空白邊圖示，然後選取「Run 'ScreenshotTests'」。

如果測試失敗，請在「Run」面板中按一下測試名稱。選取「Screenshot」分頁標籤，使用整合式縮放和平移控制項檢查圖片差異。

注意： 如果重新命名加上 @PreviewTest 註解的函式，會中斷與現有參考圖像的關聯。在這種情況下，您必須為新的函式名稱重新產生參考圖像。

使用 Gradle 工作

執行驗證工作，擷取新的螢幕截圖，並與參考圖片比較：

• 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 報表。

疑難排解

Compose 預覽螢幕截圖測試會執行主機端測試，這可能會耗用大量記憶體。如要增加測試 JVM 的堆積大小上限，請在 gradle.properties 檔案中新增下列屬性：

android.compose.screenshot.maxHeapSize=4g

已知問題

• Kotlin Multiplatform (KMP)：IDE 和基礎外掛程式都是專為 Android 專案設計。不支援 KMP 專案中的非 Android 目標。

如要查看目前已知問題的完整清單，請前往該工具的 Issue Tracker 元件。如要回報其他意見和問題，請使用 Issue Tracker。

版本更新

如需版本更新的完整清單，請參閱版本資訊。