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

このドキュメントでは、コマンドラインから直接テストを作成して実行する方法について説明します。このドキュメントは、プログラミング環境での 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 テスト結果ファイル: 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 はすべてのモジュールを調べ、指定した構成名に一致するバリエーションごとにテストを実行します。

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

    ./gradlew testVariantNameUnitTest --tests *.sampleTestMethod

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

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

  1. プロジェクト レベルの build.gradle ファイルで、ファイル内の構成の最後に次の行を追加します。 
        apply plugin: 'android-reporting'
  2. 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 を使用してテストを実行する手順は次のとおりです。

  1. 必要に応じて、メインアプリとテスト パッケージを再ビルドします。
  2. テスト パッケージとメインアプリの Android パッケージ ファイル（.apk ファイル）を、現在の Android デバイスまたはエミュレータにインストールします。
  3. コマンドラインで、次のように入力します。 
        $ 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（am instrument オプションのセクションに記載）とともに使用するように設計されています。
-e <test_options> Key-Value ペアとしてテスト オプションを提供します。am instrument ツールは、onCreate() メソッドを使用して、指定のインストゥルメンテーション クラスに Key-Value ペアを渡します。-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 テストケースの完全修飾クラス名とそのメソッド。ここで指定されたメソッドのみが実行されます。クラス名とメソッド名の間にハッシュマーク（#）が付くことに注意してください。
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

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

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