このドキュメントでは、コマンドライン上からテストの作成と実行を直接行う方法について説明します。 またここでは、あなたがプログラミング環境でAndroid アプリケーションを作成する方法を既に知っていることを前提として話を進めます。
Gradle もしくは Android Debug Bridge (adb)シェルを使用することで、 コマンドライン上からテストを実行することができます。
Gradle用 Android プラグインを使用すると、ユニットテストをGradle プロジェクト上からコマンドライン経由で実行できます。 アプリのユニットテストを作成する方法の詳細については、Building Effective Unit Testsを参照してください。
Gradle用 Android プラグインを使用すると、ユニットテストをGradle プロジェクト上からコマンドライン経由で実行できます。 アプリのユニットテストを作成する方法の詳細については、Building Effective Unit Testsを参照してください。
以下の表は、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/outputs/reports/androidTests/connected/
ディレクトリ。
XML 形式のテスト結果ファイル:
|
Gradle では
タスク名の略記をサポートしています。
つまり、例えば以下のコマンドを実行するだけでconnectedAndroidTest
タスクを開始することができます。
./gradlew cAT
test
タスクと connectedAndroidTest
タスクは、プロジェクトの各モジュールと各ビルドバリアントでテストを実行します。
test
タスクやconnectedAndroidTest
タスクの前に、モジュール名とコロン(:)を付けることで、プロジェクトの特定のモジュールだけにテストを実行できます。
例えば以下のコマンドはmylibrary
モジュールだけに インストラメンテッドユニットテストを実行します。
./gradlew mylibrary:connectedAndroidTest
以下の構文を使って、特定のビルドバリアントを対象にすることもできます。< /p>
./gradlew testVariantName
./gradlew connectedVariantNameAndroidTest
メモ:テストする対象モジュールを指定しない場合、Gradle は全てのモジュールを調べて、あなたが指定した設定名と一致する各バリアントにテストを実行します。
Gradle では、--tests
フラグを使って特定のテストを対象とすることもできます。
例えば、以下のコマンドは特定のビルドバリアントの sampleTestMethod
のみを実行します。
--tests
フラグの使い方についてより深く学ぶには、Gradleのドキュメントのtest filteringを参照してください。
./gradlew testVariantName --tests *.sampleTestMethod
表1で説明したように、Gradle はテストを行った各モジュールのbuild/
ディレクトリに、テスト報告をレポートします。
しかし、複数のモジュールにまたがってテストを実行した時は、全てのテスト結果を一つのレポートにまとめた方が良い場合もあります。
複数のモジュールにまたがったテストを実行した際に一つのレポートを生成するには、以下のように行います:
build.gradle
ファイルで、他全ての設定の後ろに以下を追加します。
apply plugin: 'android-reporting'
mergeAndroidReports
タスクと合わせて、 test
タスク やconnectedAndroidTest
タスクを実行します。
例えば:
./gradlew connectedAndroidTest mergeAndroidReports
失敗したテストを飛ばして残り全てのテストを実行するようGradle に指示するには、--continue
オプションを追加します:
./gradlew connectedAndroidTest mergeAndroidReports --continue
Gradle が全てのテストの実行を完了すると、結合されたレポートをPATH_TO_YOUR_PROJECT/build/
ディレクトリに保存します。
Android Debug Bridge (adb)を使ってコマンドライン上からテストを実行すると、 テストで選ぶことができるオプションが他の方法よりも増えます。 個別のテストメソッドを選んだり、アノテーションに従ってテストをフィルタしたり、テストオプションを指定したりできます。 テストの実行は全てのコマンドラインから制御されているので、シェルスクリプトを使った様々な方法でテストをカスタマイズできます。
コマンドラインからテストを実行するには、adb shell
を使って端末やエミュレーター上でコマンドラインシェルを開始し、
シェル内で am instrument
コマンドを実行します。
You control am
and your tests with command-line flags.
手っ取り早く行う方法として、 adb
を起動してam instrument
を呼び出し、一回の入力で全てのコマンドラインフラグを指定することができます。
このシェルは端末やエミュレーター上で開き、テストを実行し、出力を生成し、開発コンピューターのコマンドラインに戻ります。
am instrument
を使ってテストを実行するには:
.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 [flags] <test_package>/<runner_class>
以下の表では、am instrument
の主な入力パラメーターについて説明しています。:
パラメーター | 値 | 説明 |
---|---|---|
<test_package>
|
テストするパッケージの Android パッケージ名。 |
テストするパッケージのマニフェストファイル内の、 manifest 要素に設定されたpackage 属性の値です。
|
<runner_class>
|
使用するインストラメンテッドテストランナーのクラス名 |
これには、通常は
AndroidJUnitRunner を指定します。
|
以下の表では、am instrument
で使用するフラグについて説明しています:
フラグ | 値 | 説明 |
---|---|---|
-w
|
(なし) |
インストルメンテーションテストが終了するまで、am instrument の終了を強制的に待たせます。
これによる実際の効果は、テストが終わるまでシェルを開いたままにし続けるということです。
このフラグは必須ではありませんが、これを使わなかった場合テスト結果が表示されません。
|
-r
|
(なし) |
生の形式で結果を出力します。パフォーマンス測定値がテスト結果としてフォーマットされないようにするため、パフォーマンス測定値を収集したい場合はこのフラグを使用します。このフラグは-e perf true フラグと合わせて使用するように設計されています(Instrument オプションの項目で説明します)。
|
-e
|
<test_options> |
テスト用オプションを、キーと値と組み合わせ形式で設定します。
am instrument ツールは、onCreate() メソッドを介して、これらを指定されたインストラメンテーションクラスに渡します。
-e <test_options> は複数設定することができます。 キーと値については am instrument オプションの項目で説明しています。これらキーと値の組み合わせは、AndroidJUnitRunner 、もしくはInstrumentationTestRunner とそのサブクラスでのみ使用できます。
他のクラスで使用しても、何も効果はありません。
|
am instrument
ツールは -e
フラグを使って、テストオプションをキーと値の組み合わせ形式で
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 | Description |
---|---|---|
package
|
<Java_package_name> | テストパッケージ内のパッケージの完全修飾 Java パッケージ名。 このパッケージ名を使用しているテストケースクラスが実行されます。 これはAndroidのパッケージ名ではないので注意してください。; テストパッケージは一つのAndroid パッケージ名を持っていますが、その中に複数の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計測済みビルドが必要です。EMMA計測済みビルドは、 |
coverageFile |
<filename> |
端末上での既定のEMMAガバレージファイルの保存場所を変更します。この値は、UNIX形式のパスとファイル名を設定します。既定のファイル名は、 emma キーの項目で説明されています。
|
-e
フラグの使用上の注意
am instrument
はキーと値の組み合わせを含んだBundle
を引数として渡してonCreate(Bundle)
を実行します。
package
キーは class
キーよりも優先されます
パッケージを指定して、パッケージ内のクラスも別に指定した場合、Androidはパッケージ内のテストを全て実行し、class
キーは無視します。
func
キーと unit
キーはお互いに排他的です。
次の項目では am instrument
を使ってテストを実行する例を説明します。
各使用例は以下の構造に基づいています:
com.android.demo.app.tests
です。
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