執行測試 (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 在指定裝置上執行測試。一次只能測試一部裝置。
-d --disable-teardown 停用測試拆解和清除作業。
--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，請參閱「指定步驟：建構、安裝或執行」一節。

指定測試

如要執行測試，請使用下列其中一個 ID 指定一或多項測試：

  • 模組名稱
  • 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。「模組」與「模組名稱」中所述相同。「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 檔案的路徑，執行單一類別。支援相對路徑和絕對路徑。

執行模組

下列範例說明如何使用檔案路徑執行 CtsVideoTestCases 模組。

從 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) 會在執行後清除裝置，因此如果沒有 --disable-teardown 參數，嘗試使用 -t 重新執行測試就會失敗。在 -d 前使用 -t，略過測試清除步驟並反覆測試。

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

執行特定方法

Atest 支援在測試類別中執行特定方法。雖然需要建構整個模組，但這樣可縮短執行測試所需的時間。如要執行特定方法，請使用任何支援的方式 (模組：類別、檔案路徑等) 識別類別，然後附加方法名稱：

atest reference-to-class#method1

指定多種方法時，請以半形逗號分隔：

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

例如：

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

以下兩個範例說明執行單一方法的偏好方式，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 可有效建構及執行類別，因此在模組中指定類別子集，可提升效能，優於執行整個模組。

如要在同一個模組中執行兩個類別，請按照下列步驟操作：

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

如要在不同模組中執行兩個類別，請按照下列步驟操作：

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 檔案中執行測試。

隱含執行預先提交測試

在目前和上層目錄的 TEST_MAPPING 檔案中執行預先提交測試：

atest

在 /path/to/project 和上層目錄的 TEST_MAPPING 檔案中執行預先提交測試：

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

執行特定測試群組

可用的測試群組包括：presubmit(預設)、postsubmit、mainline-presubmit 和 all。

在目前和上層目錄的 TEST_MAPPING 檔案中執行提交後測試：

atest :postsubmit

從 TEST_MAPPING 檔案中的所有群組執行測試：

atest :all

在 /path/to/project 和上層目錄的 TEST_MAPPING 檔案中執行提交後測試：

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

在 /path/to/project 和上層目錄的 TEST_MAPPING 檔案中執行主線測試：

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

在子目錄中執行測試

根據預設，Atest 只會向上搜尋 TEST_MAPPING 檔案中的測試 (從目前或指定的目錄到其父項目錄)。如果您也想在子目錄的 TEST_MAPPING 檔案中執行測試，請使用 --include-subdirs 強制 Atest 一併納入這些測試：

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 有多個測試案例，其中一項測試失敗。只執行失敗的測試 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

如要進一步瞭解僅供測試的選項，請參閱「將選項傳遞至模組」。