このページは Cloud Translation API によって翻訳されました。

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

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

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

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

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

要件

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

Android Gradle プラグイン 8.5.0-beta01 以降。
Kotlin 1.9.20 以降。Compose Compiler Gradle プラグインを使用できるように、Kotlin 2.0 以降を使用することをおすすめします。
JDK 23 以下。このツールは、新しい JDK バージョンで削除された Java セキュリティマネージャーに依存しているため、JDK 24 以降と互換性がありません。
プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。

注: Compose Compiler Gradle プラグインを使用できない場合は、Compose Compiler の依存関係を直接宣言することで Compose を有効にできます。kotlinCompilerExtensionVersion バージョン 1.5.4 以降を使用していることを確認します。

設定

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

com.android.compose.screenshot プラグインのバージョン 0.0.1-alpha10 をプロジェクトに追加します。

バージョンカタログファイルにプラグインを追加します。

[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"}

モジュールレベルの build.gradle.kts ファイルで、plugins {} ブロックにプラグインを追加します。
```
plugins {
    alias(libs.plugins.screenshot)
}
```

プロジェクトの gradle.properties ファイルで試験運用版のプロパティを有効にします。
```
android.experimental.enableScreenshotTest=true
```
モジュールレベルの build.gradle.kts ファイルの android {} ブロックで、試験運用版フラグを有効にして screenshotTest ソースセットを使用します。
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```

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

参照画像を生成する

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

リリースの更新内容

進行中のバージョンのリリースノートと変更。

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