本頁面由 Cloud Translation API 翻譯而成。

運行測試 (Atest)

Atest 是一個命令行工具，允許用戶在本地構建、安裝和運行 Android 測試，大大加快了測試重新運行的速度，而無需了解Trade Federation 測試工具命令行選項。本頁介紹如何使用 Atest 運行 Android 測試。

有關為 Android 編寫測試的一般信息，請參閱Android 平台測試。

有關 Atest 整體結構的信息，請參閱Atest 開發人員指南。

有關通過 Atest 在 TEST_MAPPING 文件中運行測試的信息，請參閱在 TEST_MAPPING 文件中運行測試。

要向 Atest 添加功能，請遵循Atest 開發人員工作流程。

設置環境

按照以下部分中的步驟設置您的 Atest 環境。

設置環境變量

為Soong設置test_suite或為 Make following Packaging build script rules設置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`	在指定設備上運行測試。一次可以測試一台設備。
`-d`	`--disable-teardown`	禁用測試拆卸和清理。
`<c>`	`--info`	顯示指定目標的相關信息，然後退出。
`<c>`	`--dry-run`	在沒有實際構建、安裝或運行測試的情況下試運行 Atest。
`-m`	`--rebuild-module-info`	強制重建`module-info.json`文件。
`-w`	`--wait-for-debugger`	等待調試器完成後再執行。
`-v`	`--verbose`	顯示調試級別日誌記錄。
`<c>`	`--iterations`	循環運行測試，直到達到最大迭代。（默認為 10）
`<c>`	`--rerun-until-failure [COUNT=10]`	重新運行所有測試，直到發生故障或達到最大迭代次數。（默認為 10）
`<c>`	`--retry-any-failure [COUNT=10]`	重新運行失敗的測試，直到通過或達到最大迭代。（默認為 10）
`<c>`	`--start-avd`	自動創建 AVD 並在虛擬設備上運行測試。
`<c>`	`--acloud-create`	使用`acloud`命令創建 AVD。
`<c>`	`--[CUSTOM_ARGS]`	為測試運行器指定自定義參數。
`-a`	`--all-abi`	為所有可用的設備架構運行測試。
`<c>`	`--host`	在沒有設備的情況下完全在主機上運行測試。注意：運行需要具有`--host`的設備的主機測試將失敗。
`<c>`	`--flakes-info`	顯示帶有薄片信息的測試結果。
`<c>`	`--history`	按時間順序顯示測試結果。
`<c>`	`--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

模塊：類

要在模塊中運行單個類，請使用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重新運行測試將失敗。在-t之前使用-d跳過測試清理步驟並進行迭代測試。

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 更快地找到測試。

使用模塊：類：

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 --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

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