コマンドラインからテストする

このドキュメントでは、コマンドラインから直接テストを実行する方法を説明します。なお、Android アプリの作成方法と、アプリのテストの作成方法をすでに理解していることを前提としています。アプリのテストを作成する方法の詳細については、Android でアプリをテストするをご覧ください。

Gradle ビルドシステムを使用してアプリをビルドする場合、Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。より細かな制御を行うには、Android Debug Bridge（adb）シェルでテストを実行することもできます。

Gradle が管理する仮想デバイスを使用して、コマンドラインから自動のインストルメンテーションテストを実行する方法については、Gradle で管理されているデバイスを使用したテストのスケーリングをご覧ください。

Gradle でテストを実行する

Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。

以下の表は、Gradle を使用してテストを実行する方法をまとめたものです。

表 1. Gradle でテストを実行するさまざまな方法

単体テストのタイプ	実行するコマンド	テスト結果の出力場所
ローカル単体テスト	`test` タスクの呼び出し: `./gradlew test`	HTML テスト結果ファイル: `path_to_your_project/module_name/build/reports/tests/` ディレクトリ。 XML テスト結果ファイル: `path_to_your_project/module_name/build/test-results/` ディレクトリ。
インストルメンテーション単体テスト	`connectedAndroidTest` タスクの呼び出し: `./gradlew connectedAndroidTest`	HTML テスト結果ファイル: `path_to_your_project/module_name/build/reports/androidTests/connected/` ディレクトリ。 XML テスト結果ファイル: `path_to_your_project/module_name/build/outputs/androidTest-results/connected/` ディレクトリ。

Gradle では、タスク名の省略がサポートされています。たとえば、次のコマンドを入力するだけで connectedAndroidTest タスクを開始できます。

./gradlew cAT

Gradle タスクである check と connectedCheck を実行することもできます。この 2 つのタスクでは、それぞれローカルテストとインストルメンテーションテストを行いますが、他の Gradle プラグインによって追加された他のチェックも行われます。

モジュールに対してテストを実行する

test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各モジュールに対してテストが実行されます。テストタスクまたは connectedAndroidTest タスクの前にモジュール名とコロン（:）を付加すると、プロジェクト内の特定のモジュールにのみテストを実行できます。たとえば、次のコマンドは、mylibrary モジュールにのみインストルメンテーションテストを実行します。

./gradlew mylibrary:connectedAndroidTest

ビルドバリアントに対してテストを実行する

test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各ビルドバリアントに対してテストが実行されます。次の構文を使用すると、特定のビルドバリアントをターゲットにできます。

ローカル単体テストの場合:
```
./gradlew testVariantNameUnitTest
```
インストルメンテーションテストの場合:
```
./gradlew connectedVariantNameAndroidTest
```

特定のテストメソッドまたはテストクラスを実行する

ローカル単体テストを実行する場合、Gradle では --tests フラグを使用して特定のテストをターゲットにできます。たとえば、次のコマンドは、指定されたビルドバリアントの sampleTestMethod テストのみを実行します。--tests フラグの使用方法の詳細については、テストフィルタリングに関する Gradle のドキュメントをご覧ください。


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

インストルメンテーションテストのマルチモジュールレポート

表 1 に示すように、Gradle はテストするモジュールごとの build/ ディレクトリにインストルメンテーションテストの結果を保存します。しかし、複数のモジュールでテストを実行する場合は、すべてのテスト結果を 1 つのレポートにまとめるほうが便利です。複数のモジュールでテストを実行する際にレポートを 1 つにまとめて生成する手順は次のとおりです。

プロジェクトレベルの build.gradle ファイルで、buildscript{} ブロックの後に次のコードを追加します。
Groovy
```
apply plugin 'android-reporting'
```
Kotlin
```
apply(plugin = "android-reporting")
```
mergeAndroidReports タスクを使用して、test タスクまたは connectedAndroidTest タスクを呼び出します。次に例を示します。
```
./gradlew connectedAndroidTest mergeAndroidReports
```
テストエラーをスキップして Gradle が残りのすべてのテストを完了できるようにするには、--continue オプションを追加します。
```
./gradlew connectedAndroidTest mergeAndroidReports --continue
```

Gradle がすべてのテストの実行を終了すると、1 つにまとめられた結果が path_to_your_project/build/ ディレクトリに保存されます。

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）に含まれている manifest 要素の package 属性の値です。Android テストランナークラスは、通常は AndroidJUnitRunner です。
```
adb shell am instrument -w com.android.foo/androidx.test.runner.AndroidJUnitRunner
```

テスト結果は STDOUT に出力されます。

am instrument のフラグ

adb shell am help を実行すると、am instrument コマンドで使用するすべてのフラグを確認できます。次の表に、重要なフラグの一部を示します。

表 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/android.support.test.runner.AndroidJUnitRunner

次の表に、テストランナーで使用できる Key-Value ペアを示します。

表 3. テストランナーで使用する -e フラグの Key-Value ペア

キー	値	説明
`package`	<Java_package_name>	テストアプリ内のいずれかのパッケージの完全修飾 Java パッケージ名。このパッケージ名を使用するすべてのテストケースクラスが実行されます。これは Android パッケージ名ではないことにご注意ください。テストパッケージには Android パッケージ名が 1 つありますが、その中に Java パッケージが複数含まれる場合があります。
`class`	<class_name>	いずれかのテストケースクラスの完全修飾 Java クラス名。このテストケースクラスのみが実行されます。
`class`	<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 インストルメンテーションビルドが必要です（ターゲットに `coverage` を指定すると生成できます）。
`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 つのインストルメンテーションテストクラスがあります。
- テストメソッド bar1 を含む Foo1
- テストメソッド bar2 と bar3 を含む Foo2
テストランナーは AndroidJUnitRunner です。

テストパッケージ全体を実行する

テストパッケージ内のすべてのテストクラスを実行するには、次のように入力します。

adb shell am instrument -w com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

テストケースクラス内のすべてのテストを実行する

Foo1 クラス内のすべてのテストを実行するには、次のように入力します。

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.Foo1 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

テストのサブセットを選択する

Foo1 クラスのすべてのテストと、Foo2 の bar3 メソッドを実行するには、次のように入力します。

adb shell am instrument -w \
> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

その他のユースケースについては、AndroidJUnitRunner API リファレンスをご覧ください。