このドキュメントでは、コマンドラインから直接テストを作成して実行する方法について説明します。このドキュメントは、プログラミング環境で Android アプリを作成する方法をすでに理解していることを前提にしています。
テストの実行
Gradle または Android Debug Bridge(adb)シェルを使用して、コマンドラインからテストを実行できます。
Android Plugin for Gradle を使用すると、コマンドラインを介して Gradle プロジェクトから単体テストを実行できます。アプリの単体テストの作成方法の詳細については、効果的な単体テストを作成するをご覧ください。
Gradle を使用して単体テストを実行する
Android Plugin for Gradle を使用すると、コマンドラインを介して Gradle プロジェクトから単体テストを実行できます。アプリの単体テストの作成方法の詳細については、効果的な単体テストを作成するをご覧ください。
以下の表は、Gradle を使用して単体テストを実行する方法をまとめたものです。
単体テストのタイプ | 実行するコマンド | テスト結果の出力場所 |
---|---|---|
ローカル単体テスト |
test タスクの呼び出し:
./gradlew test |
HTML テスト結果ファイル: path_to_your_project/module_name/build/reports/tests/ ディレクトリ。
XML テスト結果ファイル: |
インストゥルメント化単体テスト |
connectedAndroidTest タスクの呼び出し:
./gradlew connectedAndroidTest |
HTML テスト結果ファイル: path_to_your_project/module_name/build/reports/androidTests/connected/ ディレクトリ。
XML テスト結果ファイル: |
Gradle では、タスク名の省略がサポートされています。たとえば、次のコマンドを入力するだけで connectedAndroidTest
タスクを開始できます。
./gradlew cAT
test
タスクと connectedAndroidTest
タスクの場合、プロジェクト内の各モジュールとビルド バリアントに対してテストが実行されます。test
タスクまたは connectedAndroidTest
タスクの前にモジュール名とコロン(:)を付加すると、プロジェクト内の特定のモジュールにのみテストを実行できます。たとえば、次のコマンドは、mylibrary
モジュールにのみインストゥルメント化単体テストを実行します。
./gradlew mylibrary:connectedAndroidTest
また、次の構文を使用して、特定のビルド バリアントをターゲットにすることもできます。
- ローカル単体テストの場合:
./gradlew testVariantNameUnitTest
- インストゥルメント化単体テストの場合:
./gradlew connectedVariantNameAndroidTest
注: テストするターゲット モジュールを指定しなかった場合、Gradle はすべてのモジュールを調べて、指定した構成名に一致するバリアントごとにテストを実行します。
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 がすべてのテストの実行を終了すると、1 つにまとめられたレポートが 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
|
(なし) |
結果を未加工の形式で出力します。パフォーマンス測定値をテスト結果用にフォーマットせずに収集する場合は、このフラグを使用します。このフラグは、フラグ -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 ペアを示します。
キー | 値 | 説明 |
---|---|---|
package
|
<Java_package_name> | テストアプリ内のいずれかのパッケージの完全修飾 Java パッケージ名。このパッケージ名を使用するすべてのテストケース クラスが実行されます。これは Android パッケージ名ではないことにご注意ください。テスト パッケージには Android パッケージ名が 1 つありますが、その中に Java パッケージが複数含まれる場合があります。 |
class |
<class_name> | いずれかのテストケース クラスの完全修飾 Java クラス名。このテストケース クラスのみが実行されます。 |
<class_name>#method name | 完全修飾テストケース クラス名と、そのメソッドのいずれか 1 つ。このメソッドのみが実行されます。クラス名とメソッド名の間にハッシュマーク(#)が入ることにご注意ください。 | |
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
キーよりも優先されます。パッケージを指定し、さらにそのパッケージ内のクラスを別個に指定しても、Android は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
テストケース クラス内のすべてのテストを実行する
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