Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

Atest

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

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

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

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

Atest に機能を追加するには、Atest Developer Workflow の手順を実施してください。

環境設定

Atest を実行するには、以下の手順で環境を設定します。

環境変数の設定

ビルド スクリプト ルールのパッケージ化に従って、Soong の場合は test_suite、Make の場合は LOCAL_COMPATIBILITY_SUITE を設定します。

envsetup.sh を実行する

Android ソース チェックアウトのルートで、次のコマンドを実行します。

source build/envsetup.sh

lunch を実行する

lunch コマンドを実行すると、サポートされているデバイスのメニューが表示されます。デバイスを見つけて、そのコマンドを実行します。

たとえば、ARM デバイスを接続している場合、次のコマンドを実行します。

lunch aosp_arm64-eng

これにより、Atest の実行に必要な環境変数が設定され、Atest コマンドが $PATH に追加されます。

基本的な使用法

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 command. を使用して AVD を作成します。
--[CUSTOM_ARGS] テストランナーのカスタム引数を指定します。
-a --all-abi 使用可能なすべてのデバイス アーキテクチャのテストを実行します。
--host デバイスを使用せずにホストだけでテストを実行します。
(注: --host を指定して、デバイスを必要とするホストテストを実行すると、失敗します。)
--flakes-info フレーク情報を含むテスト結果を表示します。
--history テスト結果を時系列順で表示します。
--latest-result 最新のテスト結果を出力します。

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

実行するテスト

test-to-run を使用して 1 つ以上のテストを実行できます。複数のテストを実行するには、テスト参照をスペースで区切ります。例:

atest test-to-run-1 test-to-run-2

次に例を示します。

atest FrameworksServicesTests
atest example/reboot
atest FrameworksServicesTests CtsVideoTestCases
atest FrameworksServicesTests:ScreenDecorWindowTests

テストの参照方法については、テストの指定をご覧ください。

テストの指定

test-to-run 引数として、テストのモジュール名、Module:Class、クラス名、TF 統合テスト、ファイルパス、パッケージ名を指定できます。

モジュール名

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

例:

atest FrameworksServicesTests
atest CtsVideoTestCases

Module:Class

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

例:

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

クラス名

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

例:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

モジュールが指定されていない場合、Atest は一致すると見込まれるモジュールをソースツリー全体で検索するため、時間がかかります。可能な限り Module:Class 参照を使用することをおすすめします。

例(実行が速い順)

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

TF 統合テスト

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

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

atest example/reboot

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

atest native-benchmark

ファイルパス

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

例: パスを指定して CtsVideoTestCases モジュールを実行する 2 つの方法

  1. Android の repo-root からモジュールを実行する:

    atest cts/tests/video
    
  2. 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

特定のメソッドの実行

テストクラス内で特定のメソッドを実行できます。モジュール全体をビルドする必要がありますが、テストの実行に必要な時間が短縮されます。特定のメソッドを実行するには、サポートされているクラスの指定方法(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 がテストを見つける速度が大幅に改善します。クラス名のみを使用するよりも、こうした例の方法をおすすめします。

  1. Module:Class を使用する

    atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange
    
  2. 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
    

ネイティブ テストの実行

Atest はネイティブ テストを実行できます。使用可能なすべてのデバイス アーキテクチャのテストを実行するには、-a を使用します。次の例では、アーキテクチャは armeabi-v7a(ARM 32 ビット)および arm64-v8a(ARM 64 ビット)です。

例:

  • 入力テスト:

    atest -a libinput_tests inputflinger_tests
    

実行するネイティブ テストを選択するには、テスト名をコロン(:)で指定し、さらにメソッドを指定するにはハッシュタグ(#)を使用します。たとえば、次のテスト定義の場合、

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

テスト全体を実行するには、次のコマンドを使用し、

atest inputflinger_tests:InputDispatcherTest

個別のテストメソッドを実行するには、次のコマンドを使用します。

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

TEST_MAPPING 内のテストの実行

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

  1. 現在のディレクトリ、親ディレクトリ、または特定のディレクトリにある TEST_MAPPING ファイル内の presubmit テストを暗黙的に実行します。

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

    atest
    

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

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

  2. TEST_MAPPING ファイル内で指定したテストグループを実行します。使用可能なテストグループは、presubmit(デフォルト)、postsubmitmainline-presubmitall です。

    • 現在のディレクトリと親ディレクトリにある 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
      

  3. TEST_MAPPING ファイル内のテストを、サブディレクトリを含めて実行します。

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

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

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

反復テストの実行

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

例:

デフォルトでは、Atest はテストを 10 回繰り返します。反復回数を変更するには、整数を指定します。

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

不安定なテストの検出に役立つ 2 つのアプローチがあります。

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

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

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

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

AVD でのテストの実行

Atest は、新しく作成された AVD を使用してテストを実行できます。Atest は、acloud create を実行するとともにアーティファクトをビルドし、AVD が正常に作成された後でテストを実行することができます。

例:

  • 新しく作成されたデバイスでテストを実行する前に、AVD を起動します。

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

  • acloud create 引数を指定して AVD を起動し、新しく作成されたデバイスでテストを実行します。

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

引数の使用状況の詳細を確認するには、acloud create --help を実行します。

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

Atest はモジュールにオプションを渡すことができます。TradeFed コマンドライン オプションを追加する Atest コマンドラインの短い形式は次のとおりです。

atest test-to-run -- [CUSTOM_ARGS]
[CUSTOM_ARGS] は、Tradefed コマンドライン オプションの形式に従って指定する必要があります。

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

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

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