テストを実行する（Atest）

Atest は、ローカルで Android テストをビルド、インストール、実行できるコマンドラインツールです。これを使用すれば、Trade Federation テストハーネスのコマンドラインオプションを知らなくても、テストの再実行を大幅に高速化できます。このページでは、Atest を使用して Android テストを実行する方法について説明します。

Android のテスト作成に関する一般的な情報については、Android プラットフォームのテストをご覧ください。

Atest の全体的な構造については、Atest デベロッパーガイドをご覧ください。

Atest を使用して TEST_MAPPING ファイル内のテストを実行する方法については、TEST_MAPPING ファイル内のテストの実行に関するページをご覧ください。

Atest に機能を追加するには、Atest デベロッパーワークフローの手順を実施してください。

環境をセットアップする

Atest 環境を設定するには、環境の設定、ターゲットの選択、コードをビルドするの手順を行います。

基本的な使用法

Atest コマンドの形式は次のとおりです。

atest test-to-run [optional-arguments]

省略可能な引数

よく使用される引数を次の表に示します。完全なリストは、atest --help で表示できます。

オプション	詳細オプション	説明
`-b`	`--build`	テストターゲットをビルドします。（デフォルト）
`-i`	`--install`	デバイスにテストアーティファクト（APK）をインストールします。（デフォルト）
`-t`	`--test`	テストを実行します。（デフォルト）
`-s`	`--serial`	指定したデバイスに対してテストを実行します。一度に 1 つのデバイスをテストできます。
`-d`	`--disable-teardown`	テストのティアダウンとクリーンアップを無効にします。
	`--info`	指定したターゲットの関連情報を表示し、終了します。
	`--dry-run`	テストを実際に作成、インストール、実行することなく、Atest をドライランします。
`-m`	`--rebuild-module-info`	`module-info.json` ファイルを強制的に再ビルドします。
`-w`	`--wait-for-debugger`	デバッガが終了するまで待ってから実行します。
`-v`	`--verbose`	DEBUG レベルのロギングを表示します。
	`--iterations`	最大反復回数に達するまで、テストをループ実行します（デフォルトでは 10 回）。
	`--rerun-until-failure [COUNT=10]`	不合格になるか最大反復回数に達するまで、すべてのテストを再実行します（デフォルトでは 10 回）。
	`--retry-any-failure [COUNT=10]`	合格するか最大反復回数に達するまで、不合格になったテストを再実行します（デフォルトでは 10 回）。
	`--start-avd`	AVD を自動的に作成して、仮想デバイスでテストを実行します。
	`--acloud-create`	`acloud` コマンドを使用して AVD を作成します。
	`--[CUSTOM_ARGS]`	テストランナーのカスタム引数を指定します。
`-a`	`--all-abi`	使用可能なすべてのデバイスアーキテクチャのテストを実行します。
	`--host`	デバイスを使用せずにホストだけでテストを実行します。注: `--host` を指定して、デバイスを必要とするホストテストを実行すると、失敗します。
	`--history`	テスト結果を時系列順で表示します。
	`--latest-result`	最新のテスト結果を出力します。

-b、-i、-t の詳細については、ステップを指定する: ビルド、インストール、実行のセクションをご覧ください。

テストを指定する

テストを実行するには、次のいずれかの識別子を使用してテストを 1 つ以上指定します。

モジュール名
Module:Class
クラス名
Tradefed 統合テスト
ファイルパス
パッケージ名

複数のテストの参照は、次のようにスペースで区切ります。

atest test-identifier-1 test-identifier-2

モジュール名

テストモジュール全体を実行するには、モジュール名を使用します。該当するテストの Android.mk ファイル内または Android.bp ファイル内の LOCAL_MODULE 変数または LOCAL_PACKAGE_NAME 変数にある名前を指定します。

例:

atest FrameworksServicesTests
atest CtsVideoTestCases

Module:Class

モジュール内の単一のクラスを実行するには、Module:Class を使用します。Module はモジュール名で説明したものと同じです。Class は、.java ファイル内のテストクラスの名前で、完全修飾クラス名または基本名を指定できます。

例:

atest CtsVideoTestCases:VideoEncoderDecoderTest
atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests

クラス名

モジュール名を明示せずに単一のクラスを実行するには、クラス名を使用します。

例:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Tradefed 統合テスト

TradeFed に統合されたテスト（非モジュール）を実行するには、tradefed.sh list configs コマンドの出力に表示されている名前を指定します。次に例を示します。

reboot.xml テストを実行するには:

atest example/reboot

native-benchmark.xml テストを実行するには:

atest native-benchmark

ファイルパス

Atest でモジュールベースのテストと統合ベースのテストの両方を実行するには、テストファイルまたはテストディレクトリへのパスを適宜指定します。クラスの Java ファイルへのパスを指定して、1 つのクラスを実行することもできます。相対パスと絶対パスの両方がサポートされています。

モジュールを実行する

次の例は、ファイルパスを使用して CtsVideoTestCases モジュールを実行する 2 つの方法を示しています。

Android の repo-root から実行:

atest cts/tests/video

Android の repo-root/cts/tests/video から実行:

    atest .

テストクラスを実行する

次の例は、ファイルパスを使用して CtsVideoTestCases モジュール内の特定のクラスを実行する方法を示しています。

Android の repo-root から実行:

    atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java

統合テストを実行する

次の例は、Android の repo-root のファイルパスを使用して統合テストを実行する方法を示しています。

    atest tools/tradefederation/contrib/res/config/example/reboot.xml

パッケージ名

Atest は、パッケージ名によるテストの検索をサポートしています。

例:

    atest com.android.server.wm
    atest com.android.uibench.janktests

ステップを指定する: ビルド、インストール、実行

-b、-i、-t オプションを使用して、実行するステップを指定します。オプションを指定しない場合、すべてのステップが実行されます。

ターゲットのビルドのみ: atest -b test-to-run
テストのみを実行: atest -t test-to-run
APK をインストールしてテストを実行: atest -it test-to-run
ビルドして実行するが、インストールはしない: atest -bt test-to-run

Atest によるテストで、クリーンアップやティアダウンのステップをスキップするよう強制できます。CTS などの多くのテストでは、テストの実行後にデバイスをクリーンアップするため、-t でテストを再実行する場合、--disable-teardown パラメータを指定しないと失敗します。テストのクリーンアップステップをスキップしてテストを繰り返すには、-d を使用してから -t を使用します。

atest -d test-to-run
atest -t test-to-run

特定のメソッドを実行する

Atest では、テストクラス内で特定のメソッドを実行できます。モジュール全体をビルドする必要がありますが、テストの実行に必要な時間が短縮されます。特定のメソッドを実行するには、サポートされているクラスの指定方法（Module:Class、ファイルパスなど）を使用してクラスを指定し、メソッドの名前を追加します。

atest reference-to-class#method1

複数のメソッドを指定する場合は、カンマで区切ります。

atest reference-to-class#method1,method2,method3

例:

atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval

次の 2 つの例は、testFlagChange という単一のメソッドを実行するためのおすすめの方法を示しています。モジュールや Java ファイルの場所を指定すると、Atest がテストを見つける速度が大幅に改善します。クラス名のみを使用するよりも、こうした例の方法をおすすめします。

Module:Class を使用:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Android の repo-root から実行:

atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange

さまざまなクラスとモジュールから複数のメソッドを実行できます。

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

複数のクラスを実行する

複数のクラスを実行するには、複数のテストを実行する場合と同じようにクラスをスペースで区切ります。Atest はクラスを効率的にビルドして実行します。モジュール内のクラスのサブセットを指定すると、モジュール全体を実行するよりもパフォーマンスが向上します。

同じモジュールの 2 つのクラスを実行するには:

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

異なるモジュールの 2 つのクラスを実行するには:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

GTest バイナリを実行する

Atest は GTest バイナリを実行できます。使用可能なすべてのデバイスアーキテクチャのテストを実行するには、-a を使用します。この例の場合、armeabi-v7a（ARM 32 ビット）と arm64-v8a（ARM 64 ビット）です。

入力テストの例:

atest -a libinput_tests inputflinger_tests

実行する特定の GTest バイナリを選択するには、テスト名をコロン（:）で指定し、さらにメソッドを指定するにはハッシュタグ（#）を使用します。

たとえば、次のテスト定義の場合は以下のとおりです。

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

次のコマンドを実行してテスト全体を指定します。

atest inputflinger_tests:InputDispatcherTest

または、次のコマンドを使用して個々のテストを実行します。

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

TEST_MAPPING 内のテストを実行する

Atest は、TEST_MAPPING ファイル内のテストを実行できます。

presubmit テストを暗黙的に実行する

現在のディレクトリと親ディレクトリにある TEST_MAPPING ファイル内の presubmit テストを実行:

atest

/path/to/project とその親ディレクトリにある TEST_MAPPING ファイル内の presubmit テストを実行:

atest --test-mapping /path/to/project

指定したテストグループを実行する

使用可能なテストグループは、presubmit（デフォルト）、postsubmit、mainline-presubmit、all です。

現在のディレクトリと親ディレクトリにある TEST_MAPPING ファイル内の postsubmit テストを実行:

atest :postsubmit

TEST_MAPPING ファイル内のすべてのグループのテストを実行:

atest :all

/path/to/project とその親ディレクトリにある TEST_MAPPING ファイル内の postsubmit テストを実行:

atest --test-mapping /path/to/project:postsubmit

/path/to/project とその親ディレクトリにある TEST_MAPPING ファイル内の mainline テストを実行:

atest --test-mapping /path/to/project:mainline-presubmit

サブディレクトリ内のテストを実行する

デフォルトでは、Atest は TEST_MAPPING ファイル内のテストを上方に（現在のディレクトリまたは指定されたディレクトリからその親ディレクトリまで）検索します。サブディレクトリにある TEST_MAPPING ファイル内のテストも実行する場合は、Atest で --include-subdirs を使用することで、強制的に対象とすることができます。

atest --include-subdirs /path/to/project

テストを繰り返し実行する

--iterations 引数を渡して、テストを繰り返し実行します。合格するかどうかにかかわらず、Atest は最大反復回数に達するまでテストを繰り返します。

例:

デフォルトでは、Atest はテストを 10 回繰り返します。繰り返し回数は正の整数で指定する必要があります。

atest test-to-run --iterations
atest test-to-run --iterations 5

以下のアプローチをとることで、不安定なテストの検出が容易になります。

アプローチ 1: 不合格になるか最大反復回数に達するまで、すべてのテストを実行します。

不合格になるか反復回数が 10 回（デフォルト）に達したら、テストを停止します。
```
atest test-to-run --rerun-until-failure
```
不合格になるか反復回数が 100 回に達したら、テストを停止します。
```
atest test-to-run --rerun-until-failure 100
```

アプローチ 2: 合格するか最大反復回数に達するまで、不合格になったテストのみを実行します。

test-to-run に複数のテストケースがあり、そのうち 1 つのテストが不合格になったとします。不合格になったテストのみを 10 回（デフォルト）、または合格するまで実行します。
```
atest test-to-run --retry-any-failure
```
合格するか 100 回に達したら、不合格になったテストの実行を停止します。
```
atest test-to-run --retry-any-failure 100
```

AVD でテストを実行する

Atest は、新しく作成された AVD でテストを実行できます。acloud create を実行して AVD とビルドアーティファクトを作成し、次の例のようにテストを実行します。

AVD を起動してテストを実行:

acloud create --local-instance --local-image && atest test-to-run

テスト実行の一環として AVD を起動:

atest test-to-run --acloud-create "--local-instance --local-image"

詳細を確認するには、acloud create --help を実行してください。

モジュールにオプションを渡す

Atest はテストモジュールにオプションを渡すことができます。テスト実行に TradeFed コマンドラインオプションを追加するには、次の構造を使用して、カスタム引数が Tradefed コマンドラインオプションの形式に従うようにします。

atest test-to-run -- [CUSTOM_ARGS]

テスト構成ファイルで定義されたターゲット作成ツールまたはテストランナーにテストモジュールオプションを渡す:

atest test-to-run -- --module-arg module-name:option-name:option-value
atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true

ランナータイプまたはクラスにオプションを渡す:

atest test-to-run -- --test-arg test-class:option-name:option-value
atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

テスト専用のオプションの詳細については、モジュールにオプションを渡すをご覧ください。