运行测试 (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

有关仅测试选项的更多信息，请参阅将选项传递给模块。