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

注意: このページで説明するスタンドアロンの com.android.compose.screenshot プラグインは、今後更新されません。Android Gradle プラグイン（AGP）9.5 以降を使用して、AGP テストスイートでスクリーンショット テストを設定することをおすすめします。切り替えるには、既存のプロジェクトを移行するをご覧ください。

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

Android のスキル

GitHub で表示

スクリーンショット テストを作成する

testing-setup Android スキルを使用して、テスト戦略を策定し、スクリーンショット テストを作成します。

Android CLI からスキルをインストールするには、次のコマンドを実行します。

android skills add testing-setup

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

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

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

図 1. HTML レポートの例。

IDE との統合

Compose プレビュー スクリーンショット テストツールは、基盤となる Gradle タスク（updateScreenshotTest と validateScreenshotTest）を手動で実行することで使用できますが、Android Studio Otter 3 Feature Drop Canary 4 では、IDE との完全な統合が導入されています。これにより、参照画像の生成、テストの実行、検証エラーの分析をすべて IDE 内で行うことができます。主な機能は次のとおりです。

• エディタ内のガターアイコン。ソースコードから直接テストを実行したり、参照画像を更新したりできるようになりました。@PreviewTest アノテーションが付けられたコンポーザブルとクラスの横のガターに、緑色の実行アイコンが表示されます。
  • スクリーンショット テストを実行する。単一の関数またはクラス全体に対してテストを実行します。
  • 参照画像を追加または更新する。選択したスコープに対して更新フローをトリガーします。

• インタラクティブな参照管理。参照画像の更新がより安全になり、よりきめ細かく行えるようになりました。
  • 新しい参照画像生成ダイアログ。一括 Gradle タスクを実行する代わりに、新しいダイアログで、生成または更新するプレビューを正確に可視化して選択できます。
  • パターンをプレビューする。ダイアログには、すべてのプレビュー バリエーション（ライトモード、ダークモード、さまざまなデバイスなど）が個別に一覧表示されます。画像を生成する前に、特定のアイテムを選択または選択解除できます。

• 統合されたテスト結果と差分ビューア。IDE を終了せずに結果を表示します。
  • 統合された実行パネル。スクリーンショットのテスト結果は、標準の [Run] ツール ウィンドウに表示されます。テストはクラスと関数ごとにグループ化され、合格または不合格のステータスが明確にマークされます。
  • ビジュアル差分ツール。テストが失敗した場合、[Screenshot] タブで、参照、実際、差分の画像を並べて比較できます。
  • 詳細な属性。[Attributes] タブには、一致率、画像のサイズ、使用された特定のプレビュー設定（uiMode や fontScale など）など、失敗したテストに関するメタデータが表示されます。

• 柔軟なテスト スコープ。プロジェクト ビューから直接、さまざまなスコープでスクリーンショット テストを実行できるようになりました。モジュール、ディレクトリ、ファイル、クラスを右クリックして、その選択範囲に固有のスクリーンショット テストを実行します。

要件

注: AGP テストスイートの要件と設定手順については、AGP テストスイートをご覧ください。

完全な IDE 統合を通じて Compose プレビューのスクリーンショット テストを使用するには、プロジェクトが次の要件を満たしている必要があります。

• Android Studio Panda 1 Canary 4 以降。
• Android Gradle プラグイン（AGP）バージョン 9.0 以降。
• Compose プレビュー スクリーンショット テスト プラグイン バージョン 0.0.1-alpha16 以降。
• Kotlin バージョン 2.2.10 以降。
• JDK バージョン 17 以降。
• プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。

IDE 統合なしで、基盤となる Gradle タスクのみを使用する場合の要件は次のとおりです。

• Android Gradle プラグイン（AGP）バージョン 8.5.0 以降。
• Compose プレビューのスクリーンショット テスト プラグイン バージョン 0.0.1-alpha16 以降。
• Kotlin バージョン 1.9.20 以降。Compose Compiler Gradle プラグインを使用できるように、Kotlin 2.0 以降を使用することをおすすめします。
• JDK バージョン 17 以降。
• プロジェクトで Compose が有効になっている。Compose Compiler Gradle プラグインを使用して Compose を有効にすることをおすすめします。

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

設定

統合ツールと基盤となる Gradle タスクはどちらも、Compose プレビューのスクリーンショット テスト プラグインに依存しています。プラグインを設定する手順は次のとおりです。

1. プロジェクトの gradle.properties ファイルで試験運用版プロパティを有効にします。

   android.experimental.enableScreenshotTest=true
   

2. モジュール レベルの build.gradle.kts ファイルの android {} ブロックで、screenshotTest ソースセットを使用するための試験運用版フラグを有効にします。

   android {
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

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

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.2.10"
      screenshot = "0.0.1-alpha16"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

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

      plugins {
          alias(libs.plugins.screenshot)
      }
      

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

参照画像を生成する

テストクラスを設定したら、プレビューごとに参照画像を生成する必要があります。これらの参照画像は、コードの変更後に変更を特定するために使用されます。コンポーズ可能なプレビューのスクリーンショット テストの参照画像を生成するには、このセクションの IDE 統合または Gradle タスクの手順に沿って操作します。

Android CLI

Android CLI をダウンロードする

Android CLI を試して Compose プレビューをレンダリングする

Android Studio を使用していない場合や、コマンドラインから操作したい場合は、Android CLI をお試しください。

たとえば、ビジュアル テスト用に Compose プレビューをレンダリングする必要がある場合は、android studio render-compose-preview コマンドを使用します。

android studio render-compose-preview

IDE で

@PreviewTest 関数の横にあるガターアイコンをクリックし、[参照画像を Add/Update] を選択します。ダイアログでプレビューを選択し、[追加] をクリックします。

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）で参照画像を見つけます。

注: 参照画像の名前は、テスト関数の完全修飾名とプレビュー パラメータのハッシュを連結したものです（例: com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png）。

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

参照画像が存在する場合は、このセクションの手順に沿って IDE 統合または Gradle タスクのテストレポートを生成します。

IDE で

@PreviewTest 関数の横にあるガターアイコンをクリックし、[Run 'ScreenshotTests'] を選択します。

テストが失敗した場合は、[Run] パネルでテスト名をクリックします。[Screenshot] タブを選択し、統合されたズームとパンのコントロールを使用して画像の差分を検査します。

注: @PreviewTest アノテーションが付けられた関数の名前を変更すると、既存の参照画像との関連付けが解除されます。その場合は、新しい関数名の参照画像を再生成する必要があります。

Gradle タスクを使用する

validate タスクを実行して新しいスクリーンショットを撮影し、参照画像と比較します。

• 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 プレビューのスクリーンショット テストはホスト側のテストを実行するため、メモリを大量に消費する可能性があります。テスト JVM の最大ヒープサイズを増やすには、gradle.properties ファイルに次のプロパティを追加します。

android.compose.screenshot.maxHeapSize=4g

既知の問題

• Kotlin Multiplatform（KMP）: IDE と基盤となるプラグインはどちらも、Android プロジェクト専用に設計されています。KMP プロジェクトの Android 以外のターゲットはサポートしていません。

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

リリースの更新内容

リリース アップデートの完全なリストについては、リリースノートをご覧ください。