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

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

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

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

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

要件

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

  • Android Gradle プラグイン 8.5.0-beta01 以降。
  • Kotlin 1.9.20 以降。Compose Compiler Gradle プラグインを使用できるように、Kotlin 2.0 以降を使用することをおすすめします。

  • プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。

設定

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

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

[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 ソースセットを使用するように試験運用版フラグを有効にします。
    android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
  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!")
    }
}

参照画像を生成する

テストクラスを設定したら、プレビューごとに参照画像を生成する必要があります。これらの参照画像は、コードを変更した後で変更を特定するために使用されます。コンポーザブル プレビュー スクリーンショット テストの参照画像を生成するには、次の 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）で参照画像を見つけます。

テストレポートを生成する

参照画像が存在したら、検証タスクを実行して新しいスクリーンショットを撮影し、参照画像と比較します。

  • 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 レポートを作成します。

既知の問題

既知の問題の最新リストは、ツールのIssue Tracker コンポーネントで確認できます。その他のフィードバックや問題については、Issue Tracker から報告してください。

リリースの更新内容

継続中のバージョンのリリースノートおよび変更点。

0.0.1-alpha10

このリリースでの新機能

  • このバージョン以降、すべてのプレビュー関数に @PreviewTest アノテーションを付ける必要があります。アノテーションのないプレビューは実行されません。

  • 参照イメージ ディレクトリが {module}/src/{variant}/screenshotTest/reference から {module}/src/screenshotTest{Variant}/reference に変更されました。これは、生成された参照イメージが本番環境コードの一部にならないようにするため、および他のテストタイプのディレクトリ構造と整合するようにするためです。

  • {variant}PreviewScreenshotRender タスクが削除されます。画像レンダリングが JUnit テストエンジンに移行されました。

  • update{Variant}ScreenshotTest タスクは、更新前に新しいレンダリング画像と参照画像を比較します。指定されたしきい値より差異が大きい画像のみが更新されます。--updateFilter コマンドライン フラグを削除しました。

0.0.1-alpha06

このリリースでの新機能

画像の差分しきい値: この新しいグローバルなしきい値設定により、スクリーンショットの比較をより細かく制御できます。構成するには、モジュールの build.gradle.kts を更新します。

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

このしきい値は、モジュールで定義されているすべてのスクリーンショット テストに適用されます。

  • バグの修正: Compose レンダラのバグと、空の Compose のサポートを追加
  • パフォーマンスの向上: 画像の差分アルゴリズムを更新して高速化