运行测试 (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，请参阅指定步骤：构建、安装或运行部分。

指定测试

如需运行测试，请使用以下标识符之一指定一个或多个测试：

• 模块名称
• Module:Class
• 类名称
• 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:Class。Module 如模块名称中所述。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 支持运行测试类中的特定方法。虽然需要构建整个模块，但此举可以缩短运行测试所需的时间。如需运行特定方法，请使用任何受支持的类标识法（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 可有效地构建和运行类，因此指定模块中的一部分类可以提高性能（与运行整个模块相比）。

如需运行同一模块中的两个类，请使用以下命令：

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 文件中运行 Mainline 测试：

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

如需详细了解仅供测试用的选项，请参阅将选项传递给模块。