コマンドラインからのテスト

このドキュメントでは、コマンドラインから直接テストを作成して実行する方法について説明します。このドキュメントは、プログラミング環境での Android アプリケーションの作成方法をすでに把握していることを前提としています。

テストの実行

Gradle または Android Debug Bridge（adb）シェルを使用して、コマンドラインからテストを実行できます。

Gradle の Android プラグインを使用すると、コマンドラインを介して Gradle プロジェクトから単体テストを実行できます。アプリの単体テストの構築方法について詳しくは、効果的な単体テストの構築を参照してください。

Gradle を使用した単体テストの実行

以下の表は、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

test タスクおよび connectedAndroidTest タスクでは、プロジェクト内の各モジュールとビルドバリアントでテストが実行されます。test タスクまたは connectedAndroidTest タスクの前にモジュール名とコロン（:）を付けると、プロジェクト内の特定のモジュールだけでテストが行えます。たとえば、次のコマンドでは、mylibrary モジュールのみで単体テストが行われます。

    ./gradlew mylibrary:connectedAndroidTest

次の構文を使用すれば、特定のビルドバリアントをターゲットにすることもできます。

ローカル単体テストの場合:

    ./gradlew testVariantNameUnitTest

インストゥルメント化単体テストの場合:

    ./gradlew connectedVariantNameAndroidTest

注意: テストするターゲットモジュールを指定しない場合、Gradle はすべてのモジュールを調べ、指定した構成名に一致するバリエーションごとにテストを実行します。

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

    ./gradlew testVariantNameUnitTest --tests *.sampleTestMethod

マルチモジュールレポート

表 1 で説明されているように、Gradle はテスト対象のモジュールごとに build/ ディレクトリにテストレポートを保存します。ただし、複数のモジュールでテストを実行する場合は、すべてのテスト結果を 1 つのレポートにまとめると便利です。複数のモジュールでテストを実行する際にレポートを 1 つにまとめて生成するには、次の手順に従います。

プロジェクトレベルの build.gradle ファイルで、ファイル内の構成の最後に以下を追加します。
```
    apply plugin: 'android-reporting'
    
```
mergeAndroidReports タスクを使用して、test タスクまたは connectedAndroidTest タスクを呼び出します。例:
```
    ./gradlew connectedAndroidTest mergeAndroidReports
    
```
Gradle が残りのすべてのテストを完了できるように、テストの失敗をスキップする場合は、--continue オプションを追加します。
```
    ./gradlew connectedAndroidTest mergeAndroidReports --continue
    
```

Gradle ですべてのテストの実行が終了すると、結合されたレポートが PATH_TO_YOUR_PROJECT/build/ ディレクトリに保存されます。

ADB を使用したテストの実行

Android Debug Bridge（adb）でコマンドラインからテストを実行する場合、他の方法に比べて実行するテストの選択肢が多くなります。アノテーションに応じたフィルタの適用や、テストオプションの指定など、テストメソッドを個別に選択できます。テストの実行はコマンドラインからすべて制御できるため、シェルスクリプトを使用してさまざまな方法でテストをカスタマイズできます。

コマンドラインからテストを実行するには、adb shell を実行してデバイスまたはエミュレータ上でコマンドラインシェルを起動し、シェル内で am instrument コマンドを実行します。コマンドラインフラグを利用することで、am とテストを制御できます。

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 です。

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

この操作により adb シェルが開始され、指定されたパラメータで am instrument が実行されます。コマンドをこのような形式で実行することで、テストパッケージ内のすべてのテストが実行されます。なお、実行時の動作については、am instrument に渡すフラグで制御できます。これらのフラグについては、次のセクションで説明します。

am instrument コマンドの使用

am instrument コマンドの一般的な構文は次のとおりです。

    am instrument [flags] <test_package>/<runner_class>

am instrument の主な入力パラメータを次の表に示します。

パラメータ	値	説明
`<test_package>`	テストパッケージの Android パッケージ名。	テストパッケージのマニフェストファイル内にある `manifest` 要素の `package` 属性値。
`<runner_class>`	使用するインストゥルメント化テストランナーのクラス名。	通常は `AndroidJUnitRunner` になります。

am instrument のフラグについて、次の表で説明します。

フラグ	値	説明
`-w`	（なし）	インストゥルメンテーションが終了しても、`am instrument` 自体を終了させるまでは起動したままにします。このように指定することで、テストが終了してもシェルを開いたままにすることができます。このフラグは必須ではありませんが、使用しない場合、テスト結果を見ることができません。
`-r`	（なし）	結果を RAW 形式で出力します。テスト結果用の表示形式を適用することなく、パフォーマンスの測定値を収集したい場合に、このフラグを使用します。このフラグは、フラグ `-e perf true`（インストゥルメントオプションのセクションに記載）と合わせて使用するように設計されています。
`-e`	<test_options>	Key-Value ペアとしてテストオプションを提供します。`am instrument` ツールは、`onCreate()` メソッドを使用して、指定のインストゥルメンテーションクラスに Key-Value ペアを渡します。なお、`-e <test_options>` の指定は複数回行えます。キーと値の詳細については、インストゥルメントオプションのセクションをご覧ください。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 ペアを示します。

キー	値	説明
`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
インストゥルメント化テストクラス:
- Foo1: テストメソッド bar1 を含む
- Foo2: テストメソッド bar2 と bar3 を含む
テストランナー: AndroidJUnitRunner

テストパッケージ全体の実行

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

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

テストケースクラスでのすべてのテストの実行

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

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

am instrument は -e フラグで指定された値を取得し、class キーワードを検出して UnitTests クラスのすべてのメソッドを実行します。

テストのサブセットの選択

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