このドキュメントでは、コマンドラインから直接テストを実行する方法を説明します。なお、Android アプリの作成方法と、アプリのテストの作成方法をすでに理解していることを前提としています。アプリのテストを作成する方法の詳細については、Android でアプリをテストするをご覧ください。
Gradle ビルドシステムを使用してアプリをビルドする場合、Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。より細かな制御を行うには、Android Debug Bridge（adb）シェルでテストを実行することもできます。継続的インテグレーション環境でテストを実行する場合に便利です。
Gradle が管理する仮想デバイスを使用して、コマンドラインから自動のインストルメンテーション テストを実行する方法については、Gradle で管理されているデバイスを使用したテストのスケーリングをご覧ください。
Gradle でテストを実行する
Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。
以下の表は、Gradle を使用してテストを実行する方法をまとめたものです。
表 1. Gradle でテストを実行するさまざまな方法
| 単体テストのタイプ | 実行するコマンド | テスト結果の場所 |
|---|---|---|
| ローカル単体テスト |
test タスクを実行します。
|
HTML テスト結果ファイル: path_to_your_project/module_name/build/reports/tests/ ディレクトリ。
XML テスト結果ファイル: |
| インストルメンテーション単体テスト |
connectedAndroidTest タスクを実行します。
|
HTML テスト結果ファイル: path_to_your_project/module_name/build/reports/androidTests/connected/ ディレクトリ。
XML テスト結果ファイル: |
Gradle では、タスク名の省略がサポートされています。たとえば、次のコマンドを入力するだけで connectedAndroidTest タスクを開始できます。
./gradlew cAT
Gradle タスクである check と connectedCheck を実行することもできます。この 2 つのタスクでは、それぞれローカルテストとインストルメンテーション テストを行いますが、他の Gradle プラグインによって追加された他のチェックも行われます。
モジュールに対してテストを実行する
test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各モジュールに対してテストが実行されます。特定のモジュールに対してテストを実行するには、test タスクまたは connectedAndroidTest タスクの前にモジュール名とコロン（:）を付加します。たとえば、次のコマンドは、mylibrary モジュールに対してのみインストルメンテーション テストを実行します。
./gradlew mylibrary:connectedAndroidTest
ビルド バリアントに対してテストを実行する
test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各ビルド バリアントに対してテストが実行されます。次の構文を使用すると、特定のビルド バリアントをターゲットにできます。
- ローカル単体テストの場合:
./gradlew testVariantNameUnitTest - インストルメンテーション テストの場合:
./gradlew connectedVariantNameAndroidTest
特定のテストメソッドまたはテストクラスを実行する
ローカル単体テストを実行する場合、Gradle では --tests フラグを使用して特定のテストをターゲットにできます。たとえば、次のコマンドは、指定されたビルド バリアントの sampleTestMethod テストのみを実行します。--tests フラグの使用方法の詳細については、テスト フィルタリングに関する Gradle のドキュメントをご覧ください。
./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'
adb を使用してテストを実行する
Android Debug Bridge（adb）を使用してコマンドラインからテストを実行する場合、他の方法に比べて、実行できるテストの選択肢が増えます。テストメソッドを個別に選択することも、カスタム アノテーションに応じてテストをフィルタすることも、テスト オプションを指定することもできます。コマンドラインからテストの実行をすべて制御できるので、シェル スクリプトを使用してさまざまな方法でテストをカスタマイズできます。
コマンドラインからテストを実行するには、adb shell を実行してデバイスまたはエミュレータ上でコマンドライン シェルを起動します。そのシェル内で am コマンドを使用してアクティビティ マネージャーを操作し、その instrument サブコマンドを使用してテストを実行できます。
adb シェルを起動し、am instrument を呼び出してコマンドライン フラグをすべて 1 行で指定すると、手順を簡略化できます。シェルがデバイスまたはエミュレータ上で起動され、テストが実行されて出力が生成されると、パソコンのコマンドラインに制御が戻されます。
am instrument を使用してテストを実行する手順は次のとおりです。
- メインアプリとテスト パッケージをビルドまたは再ビルドします。
- テスト パッケージとメイン アプリケーションの Android パッケージ ファイル（APK ファイル）を、現在の Android デバイスまたはエミュレータにインストールします。
コマンドラインで、次のように入力します。
adb shell am instrument -w <test_package_name>/<runner_class><test_package_name>は、テストアプリの Android パッケージ名です。<runner_class>は、使用する Android テストランナー クラスの名前です。Android パッケージ名は、テスト パッケージのマニフェスト ファイル（AndroidManifest.xml）に含まれているマニフェスト要素の package 属性の値です。Android テストランナー クラスは、通常は
AndroidJUnitRunnerです。adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner
テスト結果は STDOUT に出力されます。
am instrument のフラグ
am instrument コマンドで使用するすべてのフラグを確認するには、adb shell am help を実行します。次の表に、重要なフラグの一部を示します。
表 2. 重要な am instrument フラグ
| フラグ | 値 | 説明 |
|---|---|---|
-w
|
（なし） |
am instrument が、インストルメンテーションが終了するまで待機してから終了するようにします。これにより、テストが終了するまでシェルを開いたままにしておくことができます。このフラグは、テストの結果を表示するために必要です。 |
-r
|
（なし） |
結果を未加工の形式で出力します。パフォーマンス測定値をテスト結果用にフォーマットせずに収集する場合は、このフラグを使用します。このフラグは、フラグ -e perf true（am instrument のオプションのセクションに記載）とともに使用するように設計されています。 |
-e
|
<test_options>
|
Key-Value ペアとしてテスト オプションを提供します。am instrument ツールは、onCreate() メソッドを使用して、指定されたインストルメンテーション クラスにテスト オプションを渡します。-e <test_options> は複数回指定できます。キーと値の詳細については、am instrument のオプションのセクションをご覧ください。Key-Value ペアを使用できるのは、AndroidJUnitRunner または InstrumentationTestRunner と、そのサブクラスのみです。他のクラスで使用しても機能しません。
|
--no-hidden-api-checks
|
（なし） | 非表示の API の使用に関する制限を無効にします。非表示 API の概要と、それがアプリに与える影響について詳しくは、非 SDK インターフェースの制限をご覧ください。 |
am instrument オプション
am instrument ツールは、-e フラグを次の構文で使用して、テスト オプションを Key-Value ペアの形式で AndroidJUnitRunner または InstrumentationTestRunner に渡します。
-e <key> <value>
キーには複数の値を取るものがあり、その場合は、カンマで区切って指定します。たとえば、AndroidJUnitRunner の次の呼び出しでは、package キーに複数の値を指定しています。
adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner
次の表に、テストランナーで使用できる Key-Value ペアを示します。
表 3: テストランナーで使用する -e フラグの Key-Value ペア
| キー | 値 | 説明 |
|---|---|---|
package
|
<Java_package_name>
|
テストアプリ内のいずれかのパッケージの完全修飾 Java パッケージ名。このパッケージ名を使用するすべてのテストケース クラスが実行されます。これは Android パッケージ名ではないことにご注意ください。テスト パッケージには Android パッケージ名が 1 つありますが、その中に Java パッケージが複数含まれる場合があります。 |
class |
<class_name> |
いずれかのテストケース クラスの完全修飾 Java クラス名。このテストケース クラスのみが実行されます。 |
<class_name>#method name |
テストケースの完全修飾クラス名とそのメソッド。このメソッドのみが実行されます。クラス名とメソッド名の間にハッシュマーク（#）が入ることにご注意ください。 | |
func |
true |
InstrumentationTestCase を拡張するすべてのテストクラスを実行します。
|
unit |
true |
InstrumentationTestCase または PerformanceTestCase のいずれも拡張しないすべてのテストクラスを実行します。
|
size |
[small | medium | large]
|
サイズごとに異なるアノテーションの付いたテストメソッドを実行します。アノテーションは、@SmallTest、@MediumTest、@LargeTest です。 |
perf |
true |
PerformanceTestCase を実装するすべてのテストクラスを実行します。このオプションを使用する場合は、am instrument で -r フラグを指定すると、テスト結果用に再フォーマットせずに未加工の形式の出力を保持できます。 |
debug |
true |
デバッグモードでテストを実行します。 |
log |
true |
指定されたすべてのテストを読み込んでログに記録しますが、実行はしません。テスト情報は STDOUT に出力されます。他のフィルタとテスト仕様の組み合わせを確認する場合に使用します。 |
emma |
true |
EMMA コード カバレッジ分析を実行し、デバイスの /data/<app_package>/coverage.ec に出力を書き込みます。ファイルの場所をオーバーライドするには、次の項目で説明する coverageFile キーを使用します。
注: このオプションを使用するには、テストアプリの EMMA インストルメンテーション ビルドが必要です。これは、 |
coverageFile |
<filename> |
デバイス上の EMMA カバレッジ ファイルのデフォルトの場所をオーバーライドします。この値は、UNIX 形式のパスとファイル名で指定します。デフォルトのファイル名については、emma キーの項目に説明があります。 |
-e フラグを使用する場合は、次の点に注意してください。
am instrumentはonCreate(Bundle)を呼び出します。Bundleは Key-Value ペアです。packageキーはclassキーよりも優先されます。パッケージを指定して、さらにそのパッケージ内のクラスを別に指定しても、class キーは無視されてパッケージ内のすべてのテストが実行されます。funcキーとunitキーは相互排他的です。
使用例
以下のセクションでは、am instrument を使用してテストを実行する例を示します。それぞれの例は、次のような構成に基づいています。
- テスト パッケージの Android パッケージ名は
com.android.demo.app.testsです。 - 以下の 2 つのインストルメンテーション テスト クラスがあります。
- テストメソッド
testMethod1を含むTestClass1 - テストメソッド
testMethod2とtestMethod3を含むTestClass2
- テストメソッド
- テストランナーは
AndroidJUnitRunnerです。
テスト パッケージ全体を実行する
テスト パッケージ内のすべてのテストクラスを実行するには、次のように入力します。
adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner
テストケース クラス内のすべてのテストを実行する
TestClass1 クラス内のすべてのテストを実行するには、次のように入力します。
adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner
テストのサブセットを選択する
TestClass1 クラスのすべてのテストと TestClass2 の testMethod3 メソッドを実行するには、次のように入力します。
adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner
その他のユースケースについては、AndroidJUnitRunner API リファレンスをご覧ください。