testing-setup

ステップ 1：現在のテスト構成を分析する

既存のプロジェクトのテスト構成を把握するには、libs.versions.toml ファイルまたはビルドファイルで、次の依存関係を確認します。

1. 使用している依存性注入フレームワーク。たとえば、Hilt、Koin、Anvil、または標準の Dagger です。
2. このプロジェクトで使用しているユニット（ローカル）テストフレームワーク。たとえば、JUnit4 または JUnit5 です。
3. ユニットテスト、およびインストルメンテーションテストと UI テストで使用しているモックフレームワーク（使用している場合）。たとえば、Mockito または Mockk です。
4. Robolectric。次の 3 つの用途のうち、該当するものを特定します。
   1. プラットフォームのエンティティのフェイクを使用するため、ユニットテストで使用
   2. デバイスやエミュレーターを使わずに動作 UI テストを実行するために使用。たとえば、Espresso テストまたは Compose テストの実行に使用します。
   3. Roborazzi でスクリーンショットテストを行うために使用
5. アプリはすべて Compose で構成されていますか、Views で構成されていますか、それともハイブリッドですか？
6. 動作 UI テスト：
   1. Compose テスト（androidx.compose.ui:ui-test-*）
   2. Views 用の Espresso テスト。Kaspresso などのラッパーがないか確認します。依存関係：androidx.test.espresso:espresso-core、androidx.test:runner、androidx.test:rules。
7. スクリーンショットテスト。プロジェクトで使用している種類を特定します。
   1. インストルメンテーション（デバイスベース）。たとえば、Dropshots を使用します。
   2. Robolectric ベースで、ローカルで実行されます。たとえば、Roborazzi を使用します。
   3. LayoutLib ベースで、ローカルで実行されます。たとえば、Paparazzi または Compose Preview Screenshot Testing ツールを使用します。
8. エンドツーエンドテスト（リリース候補テストとも呼ばれます）は、常にデバイス上で実行し、UIAutomator、Appium、Robotium などの高水準フレームワークを使用します。
9. 分析結果を Markdown レポートとして生成します。

ステップ 2：テスト用の依存性注入フレームワークをセットアップする

依存性注入フレームワークがない場合は、導入します。マルチプラットフォームアプリケーションの場合は、Koin と kotlin-inject のどちらを導入するかユーザーに確認します。マルチプラットフォームでない場合は、Hilt を導入します。

テスト用の依存関係を導入します（たとえば com.google.dagger:hilt-compiler は kspAndroidTest 設定で適用する必要があります）。

重要

重要： テストについては、必ず該当するフレームワークのドキュメントを参照してください（例：Hilt testing guide、Koin Instrumented tests）。

インストルメンテーションテストでは、新しいテストランナーを作成して設定し（ビルドの Gradle ファイルに testInstrumentationRunner を追加）、フレームワークで必要なテストルールを適用します（たとえば Hilt の場合、テストクラスに @HiltAndroidTest を付け、HiltAndroidRule を適用します）。 ほかのフレームワークでは別の仕組みが使われます。ドキュメントを参照してください。

ステップ 3：フレームワークのインストール

特に指定がない限り、現在のテストフレームワークの構成を維持してください。

テストフレームワークがなく、ユーザーから希望の指定もない場合は、以下をインストールしてください。

• ローカルテストとインストルメンテーションテストには JUnit4

• テストカバレッジには JaCoCo

• UI テストには、プロジェクトにビューがある場合は Espresso、完全に Compose で構成されている場合は Compose Testing API を使用します。

• UI テストの実行には Robolectric

• スクリーンショットテストには Compose Preview Screenshot Testing ツール。まずプロジェクトの AGP のバージョンを確認し、それに合ったセットアップを選んで、厳密に従ってください。

  • AGP 9.5.0-alpha03 以降（推奨）： テストスイートを使ったスクリーンショットテストの説明に従い、testOptions { screenshotTests.create(...) } を使って AGP テストスイートを設定してください。
  • それより前の AGP バージョン： com.android.compose.screenshot を使った従来のスタンドアロンプラグインのセットアップを使用し、非推奨であることをユーザーに伝えてください。スクリーンショットテストのセットアップの一環として AGP をアップグレードしないでください。テストスイートは 9.5.0-alpha03 以降で利用できることを伝え、アップグレードは別途判断できるようにしてください。

  同じモジュールで両方のセットアップを組み合わせないでください。プロジェクトですでにスタンドアロンプラグインが使われていて、AGP のバージョンがテストスイートに対応している場合は、テストスイートを使ったスクリーンショットテストにあるタスクとパスの対応表を使って移行することを提案してください。

• デバイスのスクリーンショットテストには Dropshots

• モックフレームワークが必要な場合は、Mockk（io.mockk:mockk）をインストールしてください。明らかに必要な場合を除き、インストールしないでください。

インストルメンテーションによるスクリーンショットテストが求められている場合は、Dropshots をインストールしてください。

エンドツーエンドテストが求められている場合は、UI Automator をインストールしてください。

ステップ 4：テスト用のリファクタリングとフェイクの作成

ユニットテスト向けのリファクタリング

次のセクションでは、テストを作成するよう求められます。Android フレームワークのクラスや、コードベースに含まれていないエンティティへの依存関係がある場合は、次の手順に従ってください。

• まずフェイクを使用します。存在しない場合は、そのクラスのインターフェースと、既存のコードを使った「Default」実装を作成します。Fake 版はテストのソースセット（test または androidTest）に追加します。

• フェイクを使用できない場合（例：クラスやインターフェースにアクセスできない場合）は、依存関係をモックしてください。

UI テスト向けのリファクタリング

テストをより簡単かつ迅速、確実にするためにコンポーネントをフェイクにする必要がある場合は、速度が遅く問題のある依存関係をフェイクに置き換えてください。インストール済みの依存性注入フレームワークを使って、次のようなランタイムフェイクを使用してください。

• ユーザー（認証情報の誤りやパスワードのリセットフロー）、サーバー（接続なし、サーバーのダウン、サーバーからの不正な JSON）、プラットフォームコンポーネント（権限不足、ディスク容量不足、前面カメラが利用できない）のさまざまな状況をシミュレートする
• 速度と信頼性を向上させる（データベースをインメモリデータベースに置き換える、ネットワークへのアクセスを避けるためにリポジトリをインメモリのフェイクに置き換える）

ステップ 5：ユニットテスト

ビジネスロジックを含む各ファイル（ViewModel、Repository、DAO などのデータベース関連クラス）について、ユニットテストを追加またはレビューするタスクを作成してください。Activity、Compose レイアウト、依存性注入の設定ファイルにはユニットテストを作成しないでください。

ステップ 6：UI テスト

Espresso または Compose の UI テストは、Robolectric で実行するため、test ソースセットに配置します。インストルメンテーションテスト（エミュレーターまたはデバイスで実行するテスト）が求められている場合は、androidTest ソースセットに配置してください。

ステップ 7：データベースのテスト

データベースが SQLite（Room や SQLDelight などのライブラリ経由）を使用している場合は、デバイス上の SQLite エンジンで正しく動作することを確認するため、インメモリデータベースを使ったインストルメンテーションテストを作成してください。

ステップ 8：スクリーンショットテスト

使用するフレームワークにかかわらず、スクリーンショットテストでは次の 2 種類のテストを行います。

• 画面レベルのスクリーンショットテスト。各画面を、幅（400、610、900 dp）と高さ（400、500、1000 dp）のコンパクト、中程度、拡張の組み合わせによる 9 種類のサイズでテストします。
• 画面レベルのバリエーション。次の項目について、モバイル（400x500）のスクリーンショットを追加します。
  • 使用している場合は、すべての代替テーマ。
  • フォントスケールを 1.5 に設定した場合。
• コンポーネントレベルのスクリーンショットテスト。各コンポーネントを、異なるテーマとフォントスケールでテストします。

スクリーンショットでは動作をテストしませんが、状態によって UI が大きく変わる一般的なシナリオはテストしてください。たとえば、UI にローディング状態を注入するか、フェイクでシミュレートして、ローディング画面をテストします。

ステップ 9：UI 動作テスト

動作テストを使用して UI ロジックをテストします。これにより、異なる状態が渡されたときや、ユーザー操作が行われたときに、UI が期待どおりに反応することを確認できます。

Compose UI 動作テスト

• ComponentActivity を使用する ComposeTestRule を使って、文字列などのリソースにアクセスします。
• まずは必ずセマンティックマッチャーで照合します。マッチャーを書くのが複雑すぎる場合（1 つの要素を特定するのに 3 つを超えるマッチャーを使う場合）は、testTag を使用します。
• 必ず状態の復元を検証します。

Views（XML）UI 動作テスト

Espresso を使用してビューを照合し、操作します。

ステップ 10：ナビゲーションテスト

ナビゲーションロジックを検証するテストスイートを作成します。次の項目を含めます。

• 戻る操作の処理
• ディープリンク
• 複数のバックスタックを使う「ホーム経由で終了」などの特殊なパターン

ステップ 11：さまざまなウィンドウサイズと設定をシミュレートする

Compose レイアウトでは、"UI testing common patterns" で説明されている DeviceConfigurationOverride を使用して、さまざまなウィンドウサイズやフォントスケールをシミュレートします。

ステップ 12：エンドツーエンドテスト

主要なユーザージャーニーを網羅するエンドツーエンドテストを少数（テスト全体の約 5%）作成します。その際は Compose Test API または Espresso を使用します。通知やシステム UI などのプラットフォーム機能にアクセスする必要がある場合は、UI Automator を使用します。

デバイス上で実行中のアプリのスクリーンショットを撮る必要がある場合は、Dropshots を使用します。システム UI との連携（エッジツーエッジ描画、通知、ピクチャーインピクチャーなど）を検証するスクリーンショットテストでは、デバイスが必要です。

ステップ 13：インストルメンテッドスクリーンショットテスト

モジュールに com.dropbox.dropshots プラグインと Dropshots() JUnit ルールをインストールします。アプリの機能の 1 つについて、新しいインストルメンテッドスクリーンショットテストを作成します。

ステップ 14：JaCoCo をインストールする

ローカルテストのコードカバレッジを測定するために、JaCoCo をインストールします。

• テストを含む各モジュールに jacoco プラグインを追加します。

最後の仕上げ

• 分析結果と適用したテスト戦略の変更を文書化するかどうか、確認します。ユーザーが同意した場合：

  • プロジェクトに AGENTS.md ファイルがある場合は、テスト戦略に加えた変更を反映して更新します。

  • AGENTS.md ファイルがない場合は、テスト戦略の説明（各種テストの実行に必要なコマンドと、スクリーンショットの参照ファイルの場所を含む）を記載した新しいファイル（docs/testing.md）を作成します。また、ルートに新しい AGENTS.md ファイルを作成し、docs/testing.md へのリンクを追加します。