コマンドラインからテストする

このドキュメントでは、コマンドラインから直接テストを実行する方法を説明します。なお、Android アプリの作成方法と、アプリのテストの作成方法をすでに理解していることを前提としています。アプリのテストを作成する方法の詳細については、Android でアプリをテストするをご覧ください。

Gradle ビルドシステムを使用してアプリをビルドする場合、Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。より細かな制御を行うには、Android Debug Bridge（adb）シェルでテストを実行することもできます。継続的インテグレーション環境でテストを実行する場合に便利です。

Gradle が管理する仮想デバイスを使用して、コマンドラインから自動のインストルメンテーション テストを実行する方法については、Gradle で管理されているデバイスを使用したテストのスケーリングをご覧ください。

Gradle でテストを実行する

Android Gradle プラグインを使用すると、コマンドラインを使用して Gradle プロジェクトからテストを実行できます。

以下の表は、Gradle を使用してテストを実行する方法をまとめたものです。

表 1. 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

Gradle タスクである check と connectedCheck を実行することもできます。この 2 つのタスクでは、それぞれローカルテストとインストルメンテーション テストを行いますが、他の Gradle プラグインによって追加された他のチェックも行われます。

モジュールに対してテストを実行する

test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各モジュールに対してテストが実行されます。特定のモジュールに対してテストを実行するには、test タスクまたは connectedAndroidTest タスクの前にモジュール名とコロン（:）を付加します。たとえば、次のコマンドは、mylibrary モジュールに対してのみインストルメンテーション テストを実行します。

./gradlew mylibrary:connectedAndroidTest

ビルド バリアントに対してテストを実行する

test タスクと connectedAndroidTest タスクの場合、プロジェクト内の各ビルド バリアントに対してテストが実行されます。次の構文を使用すると、特定のビルド バリアントをターゲットにできます。

  • ローカル単体テストの場合: 
    ./gradlew testVariantNameUnitTest
  • インストルメンテーション テストの場合: 
    ./gradlew connectedVariantNameAndroidTest

特定のテストメソッドまたはテストクラスを実行する

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


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

インストルメンテーション テストのマルチモジュール レポート

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

  1. プロジェクト レベルの build.gradle ファイルで、buildscript{} ブロックの後に次のコードを追加します。

    Groovy

    apply plugin: 'android-reporting'

    Kotlin

    apply(plugin = "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 サブコマンドを使用してテストを実行できます。

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）に含まれているマニフェスト要素の package 属性の値です。

    Android テストランナー クラスは、通常は AndroidJUnitRunner です。

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

テスト結果は STDOUT に出力されます。

am instrument のフラグ

am instrument コマンドで使用するすべてのフラグを確認するには、adb shell am help を実行します。次の表に、重要なフラグの一部を示します。

表 2. 重要な 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/androidx.test.runner.AndroidJUnitRunner

次の表に、テストランナーで使用できる Key-Value ペアを示します。

表 3: テストランナーで使用する -e フラグの 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 つのインストルメンテーション テスト クラスがあります。
    • テストメソッド testMethod1 を含む TestClass1
    • テストメソッド testMethod2 と testMethod3 を含む TestClass2
  • テストランナーは AndroidJUnitRunner です。

テスト パッケージ全体を実行する

テスト パッケージ内のすべてのテストクラスを実行するには、次のように入力します。

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

テストケース クラス内のすべてのテストを実行する

TestClass1 クラス内のすべてのテストを実行するには、次のように入力します。

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

テストのサブセットを選択する

TestClass1 クラスのすべてのテストと TestClass2 の testMethod3 メソッドを実行するには、次のように入力します。

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

その他のユースケースについては、AndroidJUnitRunner API リファレンスをご覧ください。