qa-testing-android

QA テスト（Android）

Espresso、UI Automator、Compose Testing、スクリーンショットテスト、アダプティブ UI の検証を使用した Android テストの自動化。

主要なリファレンス：Android テストのドキュメント、ビルド管理デバイス、Compose Testing、UI Automator、スクリーンショットテスト、アクセシビリティチェック

クイックリファレンス

タスク	コマンド
エミュレーターを一覧表示	emulator -list-avds
エミュレーターを起動	emulator @<avd_name>
デバイスを一覧表示	adb devices
APK をインストール	adb install -r <path-to-apk>
単体テストを実行	./gradlew test
インストルメンテッドテストを実行（接続済みデバイス）	./gradlew connectedAndroidTest
インストルメンテッドテストを実行（GMD）	./gradlew <device><variant>AndroidTest
スクリーンショットテストを実行	./gradlew validateDebugScreenshotTest
GMD タスクを一覧表示	`./gradlew tasks --all
アプリデータを消去	adb shell pm clear <applicationId>

プラットフォームのバージョン

バージョンを固定する前に最新のバージョンを確認してください。この表には互換性ルールのみを記載しています。

コンポーネント	最新バージョンの確認先	安定版に関する注意事項
Android / API レベル	Android デベロッパーのリリースノート	最新の OS バージョンがターゲット API の要件になるとは限りません。下記の「Google Play のターゲット API ポリシー」を参照してください
AGP	https://developer.android.com/build/releases/about-agp	インストール済みの AGP マイナーバージョンに対応する互換性表から、ラッパー／JDK を選択してください。メジャーバージョンが一致するだけでは不十分です
Robolectric	https://github.com/robolectric/robolectric/releases	Robolectric 4.17 で SDK 37 のサポートが追加されました。SDK 36 以降には JDK 21 が必要です
UI Automator	https://developer.android.com/jetpack/androidx/releases/test-uiautomator	2.4 の API 境界で uiAutomator {} DSL が追加されます。プロジェクトで承認済みのリリースを選択してください
Compose Preview Screenshot Testing	Android Studio / AGP のリリースノート	プラグインと AGP のテストスイート設定、および CLI と IDE の要件をそれぞれ確認してください。screenshot-testing.md を参照してください
ATD イメージ	エミュレーターのシステムイメージ一覧	ビルド管理デバイスのガイドと SDK Manager で、サポート対象の API イメージを確認してください。ATD ではハードウェアレンダリングが無効になります
Maestro	Maestro のリリースノート	新しい API レベルのサポートは、Maestro Cloud より先にローカル CLI に導入される場合があります。新しい Android バージョンを対象にする前に確認してください

Google Play のターゲット API ポリシー（リリース移行のたびに確認）

リリースマトリックスを選択する前に、アプリのフォームファクター、提出タイプ、期限、延長の適用状況に応じたターゲット API の要件を確認してください。新規提出と既存アプリの公開可否には異なるルールが適用されます。非公開アプリや Wear／TV／Automotive／XR には例外が適用される場合があります。該当する要件を記録し、ビルド済みアーティファクト内のアプリの targetSdk を確認してください。

クイックスタート

• CI ではビルド管理対象デバイス（GMD）を優先し、テストスイートとサポート対象 API レベルが許す場合は ATD イメージを使用します。ローカルでの臨時実行には connectedAndroidTest を使用します。
• サポート対象イメージの一覧から ATD API を選択します。必要な API またはレンダリング経路を利用できない場合は、標準イメージを使用します。
• 強い分離が必要なインストルメンテーションテストスイートでは、Android Test Orchestrator と clearPackageData を有効にします。
• アニメーションは Gradle で無効にし、テストフロー内で臨時の ADB 手順を使わないようにします。
• スクリーンショットテストは、独立した高速なリグレッション層として扱います。@Preview のカバレッジには Compose Preview Screenshot Testing、JVM レンダリングには Paparazzi または Roborazzi を使用し、ハードウェアの忠実度が重要な場合にのみデバイスベースのスナップショットを使用します。
• アダプティブレイアウトを明示的にカバーします。コンパクトレイアウトと拡張レイアウト、サポート対象の場合はタブレットまたは折りたたみ式デバイスの経路、製品の動作に関わる場合は画面の向きの変更も対象にします。
• アクセシビリティチェックは、手動のみの段階として扱わず、早い段階で既存の UI テストに追加します。

安定したインストルメンテーションテストのための、推奨される Gradle のデフォルト設定：

android {
    testOptions {
        animationsDisabled = true
        execution = "ANDROIDX_TEST_ORCHESTRATOR"

        emulatorSnapshots {
            enableForTestFailures = true
            maxSnapshotsForTestFailures = 2
        }
    }
}

dependencies {
    androidTestUtil(libs.androidx.test.orchestrator)
}

インストルメンテーションテスト間の分離に依存する場合は、Gradle または CI の設定に clearPackageData=true などのランナー引数も設定します。

収集する情報

• UI スタック：Views、Compose、または混在
• テスト層：ユニット、Robolectric、インストルメンテーション UI、スクリーンショット、UI Automator、マクロベンチマーク
• CI の対象：PR ゲート、夜間実行、リリースのいずれか。管理対象エミュレーターかデバイスファームか
• デバイスマトリックス：サポート対象の最小 API、ターゲット API、画面クラス、ロケール、ダークモード、フォームファクター
• 不安定さの症状：タイムアウト、ノードの欠落、アイドリングまたは同期の問題、レンダラーでのみ発生する差分、デバイスでのみ発生する失敗
• アクセシビリティ要件：タッチターゲット、ラベル、コントラスト、TalkBack が重要なフロー
• アプリの接合点：フェイク用の DI フック、機能フラグ、テストアカウント、決定論的な時計、画像ローダー

テストレイヤー

レイヤー	フレームワーク	対象範囲
ユニット	JUnit + Mockito	JVM、Android なし
ユニット（Android）	Robolectric	JVM、シミュレートされたフレームワーク
UI（Views）	Espresso	インストルメンテーション
UI（Compose）	Compose Testing	インストルメンテーション。明示的に Robolectric を設定すれば JVM でも実行可能
アダプティブ UI	Espresso Device API + DeviceConfigurationOverride	インストルメンテーションまたはホスト支援
スクリーンショット	Compose Preview Screenshot Testing、Paparazzi、Roborazzi	JVM またはインストルメンテーション
システム	UI Automator	アプリ間、システム UI、ベンチマーク用ドライバー

基本原則（安定性）

デバイスマトリックス

• デフォルトでは、PR ゲートにエミュレーターを使用し、リリースに不可欠なユーザージャーニーには実機またはデバイスファームを使用します。
• サポート対象の最小 API とターゲット API を少なくともカバーし、製品が拡張レイアウトを提供する場合はタブレットまたは折りたたみ式デバイスのカバレッジを追加します。
• アダプティブ対応のカバレッジは、デバイスのマーケティング上の名称だけでなく、レイアウトの動作に基づいてモデル化します。

不安定さの抑制

• インストルメンテーションテストでは、testOptions { animationsDisabled = true } を優先します。
• アプリの共有状態やプロセスのクラッシュによってテスト間に影響が漏れる場合は、Android Test Orchestrator を使用します。
• スリープの代わりに、IdlingResources、Compose の同期、waitUntil、または UI Automator の条件を使用します。
• ネットワークは MockWebServer または DI フェイクでモックし、CI では稼働中のバックエンドを使用しないようにします。
• スクリーンショットテストは決定論的に保ちます。フォント、ロケール、時計、ネットワーク画像、シードデータを固定します。
• CI ではテスト失敗時のスナップショットまたはスクリーンショットを用意し、スタックトレースだけでなく成果物も残るようにします。

アクセシビリティとアダプティブ対応のカバレッジ

• 重要度の高い Espresso または Compose のユーザージャーニーと同じテストスイートでアクセシビリティチェックを実行します。
• コンパクト状態と拡張状態のレイアウトを意図的に検証します。スマートフォンのみのテストマトリックスでレスポンシブレイアウトもカバーできると想定しないでください。
• 安定したセレクターを優先します。Views では withId()、Compose では testTag、UI Automator ではリソース ID またはコンテンツ説明を使用します。

専門家の判断（チェックリストでは見落とされること）

エミュレーターと実機 — 実際の判断

チェックリストには「CI ではエミュレーター、リリースでは実機を使う」とあります。判断が必要なのは、どの実機シグナルにコストをかける価値があるかです。

• エミュレーター（できればビルド管理下のものを使い、ハードウェアの忠実性が不要な場合は ATD を使用）は、PR ゲートに適しています。決定論的で、使い捨て可能であり、アプリのバグと誤認される熱やバッテリー、OEM に起因するノイズがないためです。
• 実機またはデバイスファームにコストをかける価値があるのは、OEM やハードウェアの挙動が実際のリスクとなるフローに限られます。たとえば、カメラ撮影、生体認証、NFC／BLE、実際の Doze／App Standby 下でのバックグラウンド処理の信頼性、折りたたみ式端末のヒンジ／姿勢の遷移、実際の Play Integrity チェック下で挙動が異なる決済 SDK です。こうした要素がフローに含まれていないなら、デバイスファームでの実行はシグナルではなく、単なる見せかけです。
• よくあるアンチパターンは、「安心のため」に回帰テストスイート全体を毎晩デバイスファームで実行することです。これは、実際に検出できる障害パターンを変えないまま予算を消費します。そこで失敗するテストの大半は、管理されたエミュレーターでも、より速く安価に失敗します。デバイスファームの実行時間は、上記のようなハードウェアに依存する一握りのフローに割り当て、一般的な回帰テストスイートとは別にゲートを設けてください。
• エミュレーターのシステムイメージの選択も、単なる「Google か AOSP か」ではなく、判断が必要です。サービスに依存するフローでは、イメージが必要なサービスと配布チャネルを提供していることを確認してください。ハードウェアでレンダリングされたピクセルを検証するテストには、ATD 以外のイメージが必要です。サポート対象 API と縮小されたシステム範囲がフローに適している場合は ATD を使い、そうでなければ標準イメージを使ってください。Google API イメージでは、Play ストアや配布に依存する挙動は検証できません。そのチャネルは別途確認してください。

Android のフレークの分類（症状ではなくカテゴリで診断する）

一般的な「不安定なテスト」のトリアージでは、分類する代わりに再実行してしまい、時間を浪費します。Android UI テストの不安定さは、少数の根本原因のグループに分類できます。リトライする前に、どのグループに当てはまるかを特定してください。

1. 同期の抜け — Espresso／Compose が待機方法を認識できない非同期処理です。特徴：ローカルの高速なマシンでは成功する一方、CI の負荷が高いと失敗します。または、NoMatchingViewException が発生するか、古い読み込み状態に対してアサーションが実行されます。根本原因はほぼ常に、未登録の IdlingResource（Espresso）、または不足している waitUntil／同期された TestDispatcher（Compose／coroutines）です。登録時の落とし穴については、references/espresso-patterns.md を参照してください。
2. アニメーション／トランジションのタイミング — Espresso がビュー階層を調べる際に、ウィンドウアニメーションやプロパティアニメーションがまだ実行中です。CI では、Gradle レベルの testOptions { animationsDisabled = true } を優先してください。Gradle フラグが使えない場合（たとえば、ローカルモジュールや、フラグの導入前の Gradle バージョンを使用している場合）に限り、references/espresso-patterns.md にあるテストごとの adb 設定による DisableAnimationsRule パターンにフォールバックしてください。両方が存在すると、2 つの仕組みが予期せず食い違うことがあるため、自身のテストスイートでは「legacy」と明記してください。
3. セマンティクス階層のマージ（Compose 固有） — Material コンポーネント内の子の testTag（たとえば、Button 内の Text）は、マージされた子孫が親ノードにまとめられるため、onNodeWithTag から見えなくなります。または、assertTextEquals("Save") のような複数値のアサーションが、マージされたノードの Text リスト全体に対して失敗します。onNodeWithText などのテキスト検索は、デフォルトで引き続きマージされた親ノードに一致します。これは「何も見つからない」不具合でも、タイミングの問題でもありません。待機ループで「修正」しないでください。references/compose-testing.md にある、修正済みのマージ階層の落とし穴を参照してください。v1 から v2 への移行では、キューに残ったコルーチンの処理が原因となる場合もあります。その場合は、references/compose-testing.md の移行セクションを使い、同期の抜け（#1）に分類してください。
4. テスト間の状態漏れ — 前のテストが SharedPreferences、DB の行、またはシングルトンを、次のテストが想定しない状態のまま残しています。失敗するテストを単独で実行すると失敗しなくなる、実行順序に依存した失敗が特徴です。テストの順序を入れ替えるのではなく、Test Orchestrator と clearPackageData で修正してください。
5. Doze／App Standby／バックグラウンド制限 — バックグラウンド処理（WorkManager、FCM、フォアグラウンドサービス）に依存するテストは、起動直後のエミュレーターとは異なるデバイスの電力管理状態で挙動が変わることがあります。この問題は、物理デバイスや長時間稼働する CI マシンではほぼ発生しますが、一時的なマネージドデバイスではまれです。バックグラウンド処理のテストが特定の環境でのみ不安定な場合は、テスト自体を疑う前に電力管理状態を疑ってください。
6. レンダラー／忠実度の不一致 — スクリーンショットの差分は実際に存在するものの、意味のない違いです。ATD によるハードウェアレンダリングの無効化、CI とローカル間の GPU ドライバーの違い、OS イメージ間のフォント置換などが原因です。記録に使ったものと同じ種類のイメージで同じゴールデン生成パイプラインを再実行し、実際のビジュアルリグレッションと区別してください。
7. 非決定的なテストデータまたはクロック — ライブネットワーク呼び出し、実際の System.currentTimeMillis()、またはシードを設定していないランダムデータがアサーションやスクリーンショットのゴールデンに漏れています。いずれも必ずモックできます。それでも起きている場合は、たいてい新しい画面を追加した際にフェイクを再利用しなかったことが原因です。

テストが不安定な場合は、そのテストに手を加える前に、7 つのうちどれに該当するかを特定してください。#1 の修正（登録／待機）では #4（状態の分離／クリア）は解決せず、#5（Doze）の問題に #2 の修正（アニメーションの無効化）を適用しても効果はありません。

Compose アプリにおけるテストピラミッドの実態

従来のピラミッド（単体テストを多数、結合テストをいくつか、E2E テストを少数）は今も有効ですが、Compose では 中間 層の位置が変わります。

• createComposeRule() は引き続き、内部で ComponentActivity 上にコンテンツをホストし、モジュールで test/ 内の Robolectric 実行も設定していない限り、デバイスまたはエミュレーター上でインストルメンテーションテストを実行します。自動的にデバイス不要になるわけではありません。回避できるのは、アプリ独自の Activity、DI グラフ、ナビゲーションです。コンポーザブルが実際のナビゲーション、DI グラフ、アクティビティのライフサイクルを必要としない場合は、createAndroidComposeRule<Activity>() よりこちらを優先してください。高速で単体テストに近い実行を望む場合は、Robolectric（Roborazzi、または @RunWith(AndroidJUnit4) と isIncludeAndroidResources を使った JVM テスト）で実行してください。セットアップについては references/compose-testing.md を参照してください。
• これにより、従来は時間のかかるインストルメンテーション Espresso テストでカバーしていた範囲の多くを、高速で並列実行可能な JVM に近いテストへ移せます。ただし、ViewModel を個別にテストする場合に限ります（UI 経由ではなく、StateFlow に対する Turbine/MockK を使用します）。「ViewModel も検証するインストルメンテーション Compose テスト」しかない Compose アプリは、新しいツールで古い逆ピラミッドを再現したにすぎません。
• スクリーンショットテスト（Compose Preview Screenshot Testing / Paparazzi / Roborazzi）は、単体テストやインストルメンテーションによる動作テストの代替ではなく、独立して並行する層を構成します。動作に関するアサーションでは検出できない視覚的なリグレッション（余白、重なり、ダークモードでのコントラスト）を検出しますが、状態遷移の正しさについては何も示しません。
• UI Automator や Maestro 形式の E2E フローは、ピラミッドの最上部にあたる少数の、実際のアプリ間連携やフルスタックのスモークテスト（オンボーディング、チェックアウト、ディープリンクからの起動）に限り、PR のゲートではなく、夜間またはリリースのパイプラインで実行してください。

デバイス／API の分散への対応戦略

• アプリが実際にサポートする最小 API と現在のターゲット API は、必ずカバーしてください。市場シェアにかかわらず、この 2 つは必須です。
• この 2 つ以外は、デバイスの人気ではなく 動作上のリスク を基準に優先順位を付けてください。権限モデル、バックグラウンド実行の制限、ストレージのスコープ（スコープ付きストレージ、通知の実行時権限、フォアグラウンドサービスのタイプ宣言など）が変更された API レベルについては、インストールベースで最も一般的な OS バージョンでなくても、その変更が導入された OS バージョンで専用のテストを行う価値があります。
• 特定のデバイス／API の市場シェアの数値は、自社の分析データ（Play Console のデバイスカタログや、自社アプリの Android Vitals）を出典としていない限り、すべて 未検証 として扱ってください。公開されている集計統計は数カ月で古くなり、アプリのカテゴリや地域によって大きく異なります。テスト計画のドキュメントに「API N のユーザーは X%」といった内容をハードコードしないでください。計画のサイクルごとに、アプリの Play Console ダッシュボードから最新のデータを取得してください。
• 折りたたみ式端末、タブレット、拡張レイアウトへの対応は、API レベルとは独立した、それ自体が新たな分散軸です。大画面端末や折りたたみ式端末での実利用が増えるなか、API のカバレッジが十分に見えても、スマートフォンのみを対象としたテストマトリックスではカバレッジが不足しがちです。

スクリーンショットテストに投資するタイミング

スクリーンショットテストには、実際のセットアップおよびメンテナンスコストがかかります（ゴールデン画像の陳腐化、フォントやレンダラーの変化による誤検出、意図的な UI 変更のたびに必要となるレビュー負担）。次のような場合は、そのコストをかける価値があります。

• 手動の目視レビューでは対応しきれないほど頻繁に UI の変更をリリースするチームの場合（共有コンポーネントに触れる PR が 1 日に複数ある）。
• デザインシステムやコンポーネントライブラリがあり、1 つのリグレッションが多くの画面に波及するアプリの場合。スクリーンショットテストなら、この波及を低コストで検出できますが、動作テストでは検出できません。
• ダークモード、大きなフォントサイズ、または RTL レイアウトに対応しており、過去に気づかれないままリグレッションが発生したことがある場合。

ビジュアルデザインをまだ頻繁に試行錯誤している小規模チームにとっては、早期に投資する価値は低いでしょう。意図的なゴールデン画像の変更が頻繁になり、実際のリグレッションを検出する効果が埋もれてしまいます。まずはホスト側ツール（Compose Preview Screenshot Testing、Paparazzi、Roborazzi）を使って手軽に反復してください。デバイスベースのスナップショットテスト（Shot、または ATD を除外したデバイス実行）は、ホスト側のレンダリングでは検出できなかった画面上のバグが実際にリリースされた後、WebView、Maps、カメラプレビュー、カスタム Canvas／GPU 処理など、特定のレンダリングに影響されやすい箇所に対してのみ追加してください。

テストの作成

• Espresso（Views）：references/espresso-patterns.md を開きます
• Compose：references/compose-testing.md を開きます
• UI Automator（システムまたはアプリ間）：references/uiautomator.md を開きます
• スクリーンショットテスト：references/screenshot-testing.md を開きます
• 画面サイズへの適応テスト：references/adaptive-screen-testing.md を開きます
• アクセシビリティチェック：references/accessibility-checks.md を開きます

Compose Test v2 への移行

v1 の Compose テスト API（androidx.compose.ui.test.junit4.createComposeRule）は非推奨です。v2 （...junit4.v2.createComposeRule、...test.v2.runComposeUiTest。ui-test-junit4 1.11.0-alpha03+ から利用可能）では、デフォルトのディスパッチャーが UnconfinedTestDispatcher から StandardTestDispatcher に変更され、デフォルトでタッチ入力モードが強制されます。標準の UI アサーションはすでに同期されますが、状態を直接読み取る場合や手動でクロックを制御する場合は、 waitForIdle()／runOnIdle {} またはスケジューラーの進行が必要になることがあります（分類項目 #1）。移行ガイド全文、失敗クラスの内訳、コードサンプルについては、references/compose-testing.md を参照してください。

ワークフロー

UI テストを追加する（インストルメンテーション）

• 動作を確認できる範囲で最も限定的なフレームワークを選びます。まず Espresso または Compose を使い、システム境界では UI Automator を使います。
• 安定したセレクターを追加します。View の id、Compose の Modifier.testTag、システムの resource-id またはコンテンツ説明を使います。
• 外部要因を制御します。ネットワークをフェイク化し、データを決定論的にし、時刻とロケールを固定し、画像ソースを安定させます。
• フレームワークの同期機能または明示的な条件で待機します。Thread.sleep() は避けてください。
• テストマトリックスを拡大する前に、connectedAndroidTest または単一のマネージドデバイス用タスクを使ってローカルで実行します。

スクリーンショットテストの対象を追加する

• @Preview を使った Compose UI の状態には、Compose Preview Screenshot Testing を使用します。
• Compose とレガシーな Views の両方を JVM 上で高速にテストする必要がある場合は、Paparazzi または Roborazzi を使用します。
• ゴールデン画像は小さく、レビューしやすいものにし、変化しやすいコンテンツを含む画面全体のスナップショットではなく、安定した UI の状態に紐付けます。
• 失敗するたびに、CI で HTML または差分のアーティファクトを取得します。

不安定なインストルメンテーションテストを診断する

• テストマトリックスを拡大する前に、ローカルまたは単一のマネージドデバイスで再現します。
• ネットワーク、ロケール、クロック、機能フラグ、画像読み込み、レンダラーの差異など、非決定的な要因を取り除きます。
• スリープの代わりに、アイドリング、waitUntil、onElement、またはウォッチャーベースの同期を使います。
• logcat、スクリーンショット、画面録画、およびマネージドデバイスの失敗時スナップショットを取得します。
• それでも不安定な場合は、Orchestrator またはランナー引数を使ってアプリの状態をさらに分離し、操作手順を二分探索します。

CI ゲートを追加する（推奨：ビルド管理デバイス）

• ハードウェアレンダリングが不要で、画像が対応する API レベルを使用する場合は、ビルド管理デバイスと ATD イメージを設定します。
• ランナーがハードウェアレンダリングに対応していない場合は、GitHub Actions の GPU フラグを追加します。
• PR ゲートは小規模で決定的なものに保ち、夜間およびリリースパイプラインでデバイスグループやシャーディングを拡大します。
• build/reports/androidTests/ のレポート、スクリーンショットレポート、差分画像、logcat、管理対象デバイスの出力をアップロードします。
• ビルド、インストール、起動、操作、配布のエビデンスは個別に報告します。APK/AAB の識別情報、バリアント、デバイス/API、ロケール、正確なテストタスク、アーティファクトを記録します。Gradle ビルドで証明できるのはパッケージ化までであり、実際に実行したジャーニーを証明できるのは、指定したデバイスでの結果アサーションだけです。
• 該当する実機または配布チャネルのチェックを実行するまでは、通知、課金、ディープリンク、バックグラウンド処理、OEM 固有のフローを未検証のままにします。

ADB コマンド（トリアージ）

# Screenshot
adb exec-out screencap -p > screenshot.png

# Screen recording
adb shell screenrecord /sdcard/demo.mp4

# Pull managed-device test artifacts after a local failure
adb pull /sdcard/Android/media ./device-artifacts

CI 統合

推奨：ビルド管理デバイスです。references/gradle-managed-devices.md と references/android-ci-optimization.md を参照してください。

# .github/workflows/android.yml
name: Android CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6  # or later — verify at actions/checkout releases
      - uses: actions/setup-java@v5  # or later
        with:
          java-version: '21'  # SDK 36 unit tests need JDK 21
          distribution: 'temurin'
      - uses: gradle/actions/setup-gradle@v5  # or later
      - run: ./gradlew testDebugUnitTest <device><api>DebugAndroidTest -Pandroid.testoptions.manageddevices.emulator.gpu=swiftshader_indirect

ナビゲーション

リファレンスガイドは意図的に大きくしてあります。すべてを読み込むのではなく、ガイド内を検索してください。

• rg -n "^## " skills/universal/qa-testing-android/references/compose-testing.md
• rg -n "Idling|waitUntil|Synchronization" skills/universal/qa-testing-android/references/compose-testing.md
• rg -n "DisplaySizeRule|DeviceConfigurationOverride|fold" skills/universal/qa-testing-android/references/adaptive-screen-testing.md
• rg -n "PreviewTest|Paparazzi|Roborazzi|Shot" skills/universal/qa-testing-android/references/screenshot-testing.md

推奨事項／避けるべき事項

推奨事項

• 安定した CI のために、ビルド管理デバイスと ATD イメージを優先します
• 分離によって実際の状態漏れやクラッシュの問題が解決する場合に限り、Android Test Orchestrator を使用します
• 重要度の高い UI フローにスクリーンショットチェックとアクセシビリティチェックを追加します
• PR では小規模なマトリクスを実行し、夜間またはリリースパイプラインではグループやシャードを使って拡大します
• すべての ViewModel および StateFlow テストで、MainDispatcherRule と TestDispatcher（runTest { }、advanceUntilIdle()、kotlinx-coroutines-test）を使用します。スケジューリング動作を意図している場合に限り、eager な UnconfinedTestDispatcher を選択してください。順序に関する競合が隠れる可能性があるためです
• リリース前に kotlinx-serialization の $serializer クラスが R8 のフルモードで削除される問題を検出できるよう、少なくともデータクラスごとに 1 つの @Serializable エンドポイントを実行するリリースバリアントのスモークテストを CI で実行します（software-android-runtime-debugging/references/proguard-r8-triage.md を参照）
• Compose テストでは、UI 状態オブジェクトの参照同一性ではなく、セマンティックな状態をアサートします。たとえば onNodeWithTag(...).assertTextEquals(...) を使用します。Strong Skipping Mode では、エミッションごとに UI が同じインスタンスを受け取る場合と受け取らない場合があるためです

避けるべき事項

• 同期に Thread.sleep() を使用すること
• ライブバックエンドや時間に左右される外部コンテンツに依存するテスト
• ローカライズされたテキストや位置だけに依存するノードなど、不安定なセレクター
• ハードウェアレンダリングの忠実度が必要な場合に、ATD でデバイス全体のスクリーンショットをアサートすること
• エミッション間で StateFlow<UiState> の参照同一性をアサートすること（assertThat(state).isSameInstanceAs(previous)）。copy() で生成された新しい data class インスタンスは参照が異なっても構造的には等しいため、同一性ではなくセマンティックな等価性をテストします
• シリアライズに依存するテストをデバッグビルドだけで実行すること。デバッグでは R8 が無効なため、デバッグのみのテストスイートではシリアライズの keep ルールの不備を検出できません

リソース

リソース	目的
references/espresso-patterns.md	Espresso のマッチャーとアクション
references/compose-testing.md	Compose のテストガイド
references/uiautomator.md	システム UI とベンチマーク向けの UI Automator パターン
references/gradle-managed-devices.md	マネージドデバイスのセットアップと CI
references/screenshot-testing.md	ビジュアルリグレッションテスト
references/adaptive-screen-testing.md	画面サイズと折りたたみ式デバイスのカバレッジ
references/accessibility-checks.md	Espresso と Compose のアクセシビリティチェック
references/test-orchestrator-patterns.md	AndroidX Test Orchestrator のパターン
references/android-ci-optimization.md	CI パイプラインの最適化
references/modern-test-tooling.md	JUnit 5、MockK、Turbine、Robolectric、Maestro
data/sources.json	厳選された外部ソース

テンプレート

テンプレート	目的
assets/template-android-test-checklist.md	安定性チェックリスト

関連スキル

スキル	目的
software-mobile	Android 開発
qa-testing-strategy	テスト戦略
qa-testing-mobile	クロスプラットフォームのモバイル開発
software-android-native	ネイティブ Android の実装とエージェントのワークフロー
software-android-runtime-debugging	ビルド／インストール／起動の検証と古いビルドのトリアージ
software-android-design	ネイティブ Android のビジュアルデザインと Material 3 のレビュー

学びのループ

過去の決定や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴の確認、または利用できる代替ファイルとしてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付入りの箇条書きを 1 つ追加してください。SKILL.md 自体は変更しないでください。