使用測試套件進行螢幕截圖測試

從 Android Gradle 外掛程式 (AGP) 9.5.0-alpha03 和 Compose 預覽版螢幕截圖測試引擎 0.0.1-alpha16 開始，螢幕截圖測試會整合至 AGP 的原生測試套件架構。

這個方法會取代獨立的螢幕截圖外掛程式 (com.android.compose.screenshot)。建議採用 AGP 測試套件，原因如下：

• 原生 Gradle 工作生命週期：螢幕截圖測試直接整合到標準 Gradle 和 AGP 測試生命週期，可提升工作隔離和測試執行可靠性。
• 支援多種變數和自訂套件：您可以在單一模組中建立多個不同的螢幕截圖測試套件 (例如 screenshotTest、uiTests 或 smokeTests)，並指定建構變數 (例如 demoDebug 或 release)，而不必受限於單一預先設定的來源集。
• 提升建構效能和隔離程度：AGP 測試套件使用內建構件轉換 (例如 Layoutlib 執行階段擷取) 和隔離的類別載入，並完全支援 Gradle 設定快取和專案隔離。

需求條件

如要搭配測試套件使用 Compose 螢幕截圖測試，請確認您的環境符合下列需求：

• Android Studio Rabbit 1 Canary 4 以上版本。
• Android Gradle 外掛程式 (AGP) 9.5.0-alpha03 以上版本。
• Compose Screenshot Engine 0.0.1-alpha16 以上版本。
• JDK 17 以上版本。
• 專案已啟用 Compose。建議使用 Compose 編譯器 Gradle 外掛程式啟用 Compose。

設定與配置

如要使用測試套件設定 Compose 螢幕截圖測試，請完成下列步驟：

1. 啟用實驗性旗標

在專案的根層級 gradle.properties 檔案中，啟用螢幕截圖測試和測試套件支援：

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. 在 build.gradle.kts 檔案中設定測試套件

在模組的 build.gradle.kts 檔案中，於 testOptions 區塊內定義螢幕截圖測試套件：

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. 建立測試來源集

建立專屬來源集目錄，與套件名稱相符：

{module}/src/{suiteName}/kotlin/

舉例來說，如果套件名稱為 screenshotTest：

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. 定義可組合函式預覽測試

使用 @PreviewTest 和標準 @Preview 或多重預覽註解，為可組合函式加上註解：

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

執行螢幕截圖測試

AGP 測試套件會根據套件名稱、目標和變數，產生專屬的 Gradle 工作。

1. 生成或更新參考圖片

算繪可組合項預覽畫面，並儲存黃金基準參考圖片：

• Linux 和 macOS： ./gradlew update{SuiteName}{Target}{Variant}TestSuite (例如 ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows： gradlew updateScreenshotTestDefaultDemoDebugTestSuite

參考圖片會生成並儲存至下列位置：

{module}/src/{suiteName}{Target}{Variant}/reference/

2. 驗證及執行測試

算繪新的螢幕截圖，並與參考圖片比較：

• Linux 和 macOS： ./gradlew test{SuiteName}{Target}{Variant}TestSuite (例如 ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows： gradlew testScreenshotTestDefaultDemoDebugTestSuite

檢查測試報告

如果偵測到差異或測試失敗，AGP 會產生 HTML 測試報告。

• 報表位置： {module}/build/reports/tests/{taskName}/index.html (例如 app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

更新後的報表包含：

• 標題中繼資料資訊卡：顯示測試名稱、預覽方法、變數、套件和狀態徽章。
• 錯誤分類：清楚標示 Reference Image Missing、Image Size Mismatch 或 Pixel Mismatch，並提供可複製的堆疊追蹤。
• 動態視覺差異比較：以較低的強度醒目顯示細微修改，並以高對比強調重大變更，避免巢狀元素遭到吞噬。

從舊版獨立外掛程式遷移

如要從舊版獨立螢幕截圖外掛程式遷移至 AGP 測試套件，請更新 Gradle 設定和工作指令。

建構設定 DSL 比較

舊版獨立外掛程式 (已淘汰)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

AGP 測試套件 (建議)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

對應工作和路徑