運行測試 (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	禁用測試拆解和清理。
	--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的更多信息，請參閱指定步驟：構建、安裝或運行部分。

指定測試

要運行測試，請使用以下標識符之一指定一個或多個測試：

• 模塊名稱
• 模塊：類
• 班級名稱
• Tradefed 集成測試
• 文件路徑
• 包裹名字

用空格分隔對多個測試的引用，如下所示：

atest test-identifier-1 test-identifier-2

模塊名稱

要運行整個測試模塊，請使用其模塊名稱。輸入該測試的Android.mk或Android.bp文件中LOCAL_MODULE或LOCAL_PACKAGE_NAME變量中顯示的名稱。

例子：

atest FrameworksServicesTests
atest CtsVideoTestCases

注意：要運行集成到 TradeFed (TF) 中的非模塊測試，請改用TF 集成測試作為標識符。

模塊：類

要在模塊中運行單個類，請使用Module:Class 。 Module與Module name中描述的相同。 class是.java文件中測試類的名稱，可以是全限定類名，也可以是基本類名。

例子：

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

注意：為了減少 Atest 定位正確測試的時間，我們建議使用上一個示例中所示的完整類路徑。

班級名稱

要在不顯式聲明模塊名稱的情況下運行單個類，請使用類名。

例子：

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

注意：為了減少 Atest 定位正確測試的時間，我們建議盡可能使用Module:Class而不是僅使用類名。

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選項指定要運行的步驟。如果您不指定選項，則所有步驟都會運行。

注意： -b和-t可以單獨運行，但-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重新運行測試將失敗。在-t之前使用-d跳過測試清理步驟並迭代測試。

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

注意：因為-t禁用設備的設置/安裝和拆卸/清理，您可以使用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 更快地找到測試。

使用模塊：類：

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

注意：如果您只需要針對特定設備架構運行測試，請使用atest -- --abi arm64-v8a或atest -- --abi armeabi-v7a

要選擇要運行的特定 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 --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 。

注意： --acloud-create必須是最後一個可選參數。它後面的任何參數都被視為 AVD 的位置參數。

注意： --acloud-create和--start-avd不會刪除新創建的 AVD。用戶必須手動刪除它們。

將選項傳遞給模塊

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

有關僅測試選項的更多信息，請參閱將選項傳遞給模塊。