執行測試 (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 指定一或多個測試：

• 模組名稱
• 模組：類別
• 類別名稱
• Tradefed 整合測試
• 檔案路徑
• 套件名稱

請以空格分隔多個測試的參照，如下所示：

atest test-identifier-1 test-identifier-2

模組名稱

如要執行整個測試模組，請使用模組名稱。請輸入在該測試 Android.mk 或 Android.bp 檔案內 LOCAL_MODULE 或 LOCAL_PACKAGE_NAME 變數中顯示的名稱。

例如：

atest FrameworksServicesTests
atest CtsVideoTestCases

注意： 如要執行已整合至 TradeFed (TF) 的非模組測試，請改用 TF Integration Test 做為 ID。

模組：類別

如要執行模組中的單一類別，請使用 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.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 支援在測試類別中執行特定方法。雖然需要建構整個模組，但這可縮短執行測試所需的時間。如要執行特定方法，請使用任何支援的類別識別方式 (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

以下兩個範例說明執行單一方法 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 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

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