Compose 預覽螢幕截圖測試

螢幕截圖測試是驗證使用者看到 UI 樣貌的有效方式。Compose 預覽畫面螢幕截圖測試工具結合了可組合函式預覽畫面的簡便性與功能，以及執行主機端螢幕截圖測試帶來的生產力提升。Compose 預覽畫面螢幕截圖測試的設計宗旨，是盡可能簡化使用方式，讓您能像使用可組合函式預覽畫面一樣輕鬆上手。

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

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

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

IDE 整合

您可以手動執行基礎 Gradle 工作 (updateScreenshotTest 和 validateScreenshotTest)，使用 Compose 預覽畫面螢幕截圖測試工具，但 Android Studio Otter 3 功能推送 Canary 4 導入了完整的 IDE 整合功能。您可以在 IDE 中生成參考圖片、執行測試，並分析驗證失敗情形。主要功能包括：

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

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

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

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

需求條件

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

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

如果您只想使用基礎 Gradle 工作，而不要 IDE 整合功能，則需符合下列需求：

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

設定

整合式工具和基礎 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-alpha14) 新增至專案。

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha14"
      
      [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 工作操作說明，進行螢幕截圖測試。

在 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) 中尋找參考圖片。

產生測試報告

參考圖片存在後，請按照本節中的 IDE 整合或 Gradle 工作操作說明，產生測試報告。

在 IDE 中

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

如果測試失敗，請按一下「執行」面板中的測試名稱。選取「螢幕截圖」分頁，使用整合式縮放和平移控制項檢查圖片差異。

使用 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 報表。

已知問題

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

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

版本更新

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