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

このドキュメントでは、コマンドラインから直接テストを作成して実行する方法について説明します。このドキュメントは、プログラミング環境で 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 ファイルで、ファイル内の他のすべての構成の後に次の行を追加します。

    Groovy

    apply plugin: 'android-reporting'

    Kotlin

    plugins {
    id("android-reporting")
}
  2. 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 を使用してテストを実行する手順は次のとおりです。

  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 （なし） 結果を未加工の形式で出力します。パフォーマンス測定値をテスト結果用にフォーマットせずに収集する場合は、このフラグを使用します。このフラグは、フラグ -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 インストゥルメント化ビルドが必要です（ターゲットに coverage を指定すると生成できます）。

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