Compose プレビューのスクリーンショットのテスト

スクリーンショット テストは、UI がユーザーにどのように表示されるかを検証する効果的な方法です。Compose プレビューのスクリーンショット テストツールは、コンポーザブル プレビューのシンプルさと機能と、ホスト側のスクリーンショット テストの実行による生産性の向上を組み合わせています。Compose プレビューのスクリーンショット テストは、コンポーザブルのプレビューと同じくらい簡単に使用できるように設計されています。

スクリーンショット テストは、UI のスクリーンショットを撮影し、以前に承認された参照画像と比較する自動テストです。画像が一致しない場合、テストは失敗し、違いを比較して見つけるのに役立つ HTML レポートが生成されます。

Compose プレビューのスクリーンショット テストツールを使用すると、次のことができます。

  • スクリーンショット テストに使用する既存または新規のコンポーザブル プレビューをいくつか特定します。
  • これらのコンポーザブルのプレビューから参照画像を生成します。
  • コードを変更した後にプレビューに対する変更を特定する HTML レポートを生成します。
  • uiMode や fontScale などの @Preview パラメータとマルチプレビューを使用して、テストをスケーリングできます。
  • 新しい screenshotTest ソースセットでテストをモジュール化します。
図 1.HTML レポートの例

要件

Compose プレビューのスクリーンショット テストを使用するには、次のものが必要です。

  • Android Gradle 8.5.0-beta01 以降。
  • Kotlin 1.9.20 以降。

セットアップ

このツールを有効にする手順は次のとおりです。

  1. com.android.compose.screenshot プラグイン（バージョン 0.0.1-alpha01）をプロジェクトに追加します。
    1. プラグインをバージョン カタログ ファイルに追加します。 
      [versions]
agp = "8.5.0-beta01"
kotlin = "1.9.20"
...
screenshot = "0.0.1-alpha01"

[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 レポートが作成されます。

既知の問題

  • screenshotTest ソースセットのプレビューが完全修飾されたメソッド名を main のプレビューと共有している場合、スクリーンショット テストではなく main 内のメソッド名が誤ってテストに使用されます。