運行測試（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	顯示調試等級日誌記錄。
	--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 。模組與模組名稱中所述的相同。 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-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

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