テストスイートを使用したスクリーンショット テスト

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 Compiler 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")
            }
        }
    }
}

タスクとパスのマッピング