スクリーンショット テストは、UI がユーザーにどのように表示されるかを確認する効果的な方法です。 Compose Preview Screenshot Testing ツールは、コンポーザブル プレビューのシンプルさと 機能を、ホスト側のスクリーンショット テストを実行することによる生産性の 向上と組み合わせたものです。Compose Preview Screenshot Testing は、コンポーザブル プレビューと同じくらい簡単に使用できるように設計されています。
スクリーンショット テストは、UI の一部のスクリーンショットを撮影し、以前に承認された参照画像と比較する自動テストです。画像が一致しない場合、テストは失敗し、比較して違いを見つけるのに役立つ HTML レポートが生成されます。
Compose Preview Screenshot Testing ツールを使用すると、次のことができます。
@PreviewTestを使用して、既存または新規のコンポーザブル プレビューのスクリーンショット テストを作成します。- これらのコンポーザブル プレビューから参照画像を生成します。
- コードを変更した後、これらのプレビューの変更を特定する HTML レポートを生成します。
uiModeやfontScaleなどの@Previewパラメータとマルチプレビューを使用して、テストをスケーリングします。- 新しい
screenshotTestソースセットを使用してテストをモジュール化します。
IDE との統合
Compose Preview Screenshot Testing ツールは、基盤となる Gradle タスク（updateScreenshotTest と validateScreenshotTest）を手動で実行して使用できますが、Android Studio Otter 3 Feature Drop Canary 4 では、IDE との完全な統合が導入されています。これにより、参照画像の生成、テストの実行、検証の失敗の分析をすべて IDE 内で行うことができます。主な機能は次のとおりです。
- エディタ内のガターアイコン。ソースコードから直接テストを実行したり、参照画像を更新したりできるようになりました。
@PreviewTestアノテーションが付けられたコンポーザブルとクラスの横のガターに、緑色の実行アイコンが表示されます。- スクリーンショット テストを実行する。単一の関数またはクラス全体に対してテストを実行します。
- 参照画像を追加または更新する。選択したスコープに対して更新フローをトリガーします。
- インタラクティブな参照管理。参照画像の更新がより安全かつ細かくできるようになりました。
- 新しい参照画像生成ダイアログ。一括 Gradle タスクを実行する代わりに、新しいダイアログで、生成または更新するプレビューを正確に視覚化して選択できます。
- プレビューのバリエーション。ダイアログには、すべてのプレビューのバリエーション（ライトテーマやダークテーマ、異なるデバイスなど）が個別に表示されるため、画像を生成する前に特定のアイテムを選択または選択解除できます。
- 統合されたテスト結果と差分ビューア。IDE を離れることなく結果を表示できます。
- 統合された実行パネル。スクリーンショット テストの結果は、標準の [Run] ツール ウィンドウに表示されます。テストはクラスと関数ごとにグループ化され、合格または不合格のステータスが明確に示されます。
- ビジュアル差分ツール。テストが失敗した場合、[Screenshot] タブで、 参照画像、実際の画像、差分画像を並べて比較できます。
- 詳細な属性。[Attributes] タブには、一致率、画像サイズ、使用された特定のプレビュー構成（
uiModeやfontScaleなど）など、失敗したテストのメタデータが表示されます。
- 柔軟なテスト スコープ。プロジェクト ビューから、さまざまなスコープでスクリーンショット テストを直接実行できるようになりました。モジュール、ディレクトリ、ファイル、クラスを右クリックして、その選択に対してスクリーンショット テストを実行します。
要件
IDE との完全な統合を通じて Compose Preview Screenshot Testing を使用するには、プロジェクトが次の要件を満たしている必要があります。
- Android Studio Panda 1 Canary 4 以降。
- Android Gradle プラグイン（AGP）バージョン 9.0 以降。
- Compose Preview Screenshot Testing プラグイン バージョン 0.0.1-alpha14 以降。
- Kotlin バージョン 2.2.10 以降。
- JDK バージョン 17 以降。
- プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。
IDE との統合なしで基盤となる Gradle タスクのみを使用する場合は、次の要件を満たす必要があります。
- Android Gradle プラグイン（AGP）バージョン 8.5.0 以降。
- Compose Preview Screenshot Testing プラグイン バージョン 0.0.1-alpha14 以降。
- Kotlin バージョン 1.9.20 以降。Compose Compiler Gradle プラグインを使用できるように、Kotlin 2.0 以降を使用することをおすすめします。
- JDK バージョン 17 以降。
- プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。
設定
統合ツールと基盤となる Gradle タスクはどちらも、Compose Preview Screenshot Testing プラグインに依存しています。プラグインを設定する手順は次のとおりです。
プロジェクトの
gradle.propertiesファイルで試験運用版のプロパティを有効にします。android.experimental.enableScreenshotTest=trueモジュール レベルの
build.gradle.ktsファイルのandroid {}ブロックで、試験運用版のフラグを有効にしてscreenshotTestソースセットを使用します。android { experimentalProperties["android.experimental.enableScreenshotTest"] = true }com.android.compose.screenshotプラグイン バージョン0.0.1-alpha14をプロジェクトに追加します。プラグインをバージョン カタログ ファイルに追加します。
[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"}モジュール レベルの
build.gradle.ktsファイルで、plugins {}ブロックにプラグインを追加します。plugins { alias(libs.plugins.screenshot) }
screenshot-validation-apiとui-toolingの依存関係を追加します。バージョン カタログに追加します。
[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"}モジュール レベルの
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] を選択します。ダイアログでプレビューを選択し、[Add] をクリックします。
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'] を選択します。
テストが失敗した場合は、[Run] パネルでテスト名をクリックします。[Screenshot] タブを選択して、統合されたズーム操作とパン操作を使用して画像の差分を確認します。
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 レポートが作成されます。
トラブルシューティング
Compose Preview Screenshot Testing はホスト側のテストを実行するため、メモリを大量に消費する可能性があります。テスト JVM の最大ヒープサイズを増やすには、gradle.properties ファイルに次のプロパティを追加します。
android.compose.screenshot.maxHeapSize=4g
既知の問題
- Kotlin Multiplatform（KMP）: IDE と基盤となるプラグインは、Android プロジェクト専用に設計されています。KMP プロジェクトの Android 以外のターゲットはサポートしていません。
現在確認されている問題の完全なリストは、ツールの Issue Tracker コンポーネントで確認できます。その他のフィードバックや問題は、 Issue Trackerから報告してください。
リリースの更新内容
リリースの更新内容の完全なリストについては、 リリースノートをご覧ください。