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

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

テストの実行

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

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

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

Gradle の Android プラグインを使用すると、コマンドラインを介して 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 つにまとめて生成するには、次の手順に従います。

  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インストゥルメント オプションのセクションに記載)と合わせて使用するように設計されています。
-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_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: テストメソッド bar2bar3 を含む
  • テストランナー: 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 および Foo2bar3 メソッドですべてのテストを実行するには、次のように入力します。

    $ 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