Google 致力于为黑人社区推动种族平等。查看具体举措

Atest

Atest 是一个命令行工具,可让用户在本地编译、安装并运行 Android 测试,同时可以大大加快重新运行测试的速度,而无需您了解 Trade Federation 自动化测试框架命令行选项。本文介绍了如何使用 Atest 运行 Android 测试。

要了解有关如何针对 Android 编写测试的一般信息,请参阅 Android 平台测试

如需了解 Atest 的总体结构,请参阅 Atest 开发者指南

如需了解如何通过 Atest 在 TEST_MAPPING 文件中运行测试,请参阅在 TEST_MAPPING 文件中运行测试

如需向 Atest 添加功能,请按照 Atest 开发者工作流程操作。

设置您的环境

要运行 Atest,请按照以下部分中的步骤来设置您的环境。

设置环境变量

按照打包构建脚本规则Soong 设置 test_suite,或为 Make 设置 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 停用测试拆解和清理。
--info 显示指定目标的相关信息并退出。
--dry-run 模拟运行 Atest,不实际构建、安装和运行测试
-m --rebuild-module-info 强制重新构建 module-info.json 文件。
-w --wait-for-debugger 在执行之前等待调试程序。 仅用于插桩测试。
-v --verbose 显示 DEBUG 级别日志记录。
--iterations 循环运行测试,直至达到最大迭代次数。(默认情况下为 10 次)
--rerun-until-failure 重新运行所有测试,直至出现失败的情况或达到最大迭代次数。 (默认情况下为 10 次)
--retry-any-failure 重新运行失败的测试,直至测试通过或达到最大迭代次数。(默认情况下为 10 次)
--start-avd 自动创建 AVD 并在该虚拟设备上运行测试。
--acloud-create 使用 acloud command. 创建 AVD
--[CUSTOM_ARGS] 为测试运行程序指定自定义参数。
-a --all-abi 针对所有可用的设备架构运行测试。
--host 在没有设备的情况下完全在主机上运行测试。
(注意:使用 --host 运行需要设备的主机测试将失败。)
--flakes-info 显示包含不稳定信息的测试结果。
--history 按时间顺序显示测试结果。
--latest-result 输出最新测试结果。

如需详细了解 -b-i-t,请参阅指定步骤:构建、安装或运行

要运行的测试

您可以使用 test-to-run 运行一个或多个测试。如需运行多个测试,请使用空格将各测试引用分隔开。例如:

atest test-to-run-1 test-to-run-2

以下是一些示例:

atest FrameworksServicesTests
atest example/reboot
atest FrameworksServicesTests CtsVideoTestCases
atest FrameworksServicesTests:ScreenDecorWindowTests

要详细了解如何引用测试,请参阅标识测试

标识测试

您可以使用测试的模块名称、Module:Class、类名称、TF 集成测试、文件路径或软件包名称来指定 test-to-run 参数。

模块名称

如需运行整个测试模块,请使用其模块名称。请输入在该测试的 Android.mkAndroid.bp 文件中的 LOCAL_MODULELOCAL_PACKAGE_NAME 变量中显示的名称。

示例:

atest FrameworksServicesTests
atest CtsVideoTestCases

Module:Class

要运行模块内的单个类,请使用 Module:ClassModule模块名称中所述。Class.java 文件中测试类的名称,可以是完全限定的类名,也可以是基本名称。

示例:

atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests
atest CtsVideoTestCases:VideoEncoderDecoderTest

类名称

要在不明确声明模块名称的情况下运行单个类,请使用类名称。

示例:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

建议尽可能使用 Module:Class 引用,因为如果没有声明任何模块,Atest 将需要更多时间来搜索完整源代码树以查找可能的匹配项。

示例(从最快到最慢排序):

atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests
atest FrameworksServicesTests:ScreenDecorWindowTests
atest ScreenDecorWindowTests

TF 集成测试

如需运行直接集成到 TradeFed(非模块)中的测试,请输入 tradefed.sh list configs 命令的输出中显示的名称。例如:

如需运行 reboot.xml 测试,请执行以下操作:

atest example/reboot

如需运行 native-benchmark.xml 测试,请执行以下操作:

atest native-benchmark

文件路径

通过输入相应测试文件或目录的路径,您既可以运行基于模块的测试,也可以运行基于集成的测试。您还可以通过指定单个类的 Java 文件的路径来运行该类。同时支持相对路径和绝对路径。

示例:通过路径运行 CtsVideoTestCases 模块的两种方法

  1. 通过 Android repo-root 运行模块:

    atest cts/tests/video
    
  2. 通过 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 android.jank.cts

指定步骤:构建、安装或运行

您可以使用 -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

运行特定方法

您可以运行测试类中的特定方法。虽然需要构建整个模块,但这么做可以缩短运行测试所需的时间。要运行特定方法,请使用任何受支持的类标识法(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 更快地找到测试:

  1. 使用 Module:Class

    atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange
    
  2. 通过 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
    

运行原生测试

Atest 可以运行原生测试。使用 -a 可针对所有可用的设备架构(在此示例中为 armeabi-v7a [ARM 32 位] 和 arm64-v8a [ARM 64 位])运行测试。

示例:

  • 输入测试:

    atest -a libinput_tests inputflinger_tests
    

如需选择要运行的特定原生测试,请使用冒号 (:) 指定测试名称,然后使用 # 标签 (#) 进一步指定单个方法。例如,对于以下测试定义:

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

您可以使用下列命令运行整个测试

atest inputflinger_tests:InputDispatcherTest

或使用下列命令运行单个测试方法

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

以迭代方式运行测试

如需以迭代方式运行测试,只需传递 --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 运行测试。Atest 可以在运行 acloud create 的同时构建工件,并在成功创建 AVD 后运行测试。

示例:

  • 启动 AVD,然后在新创建的该设备上运行测试:

    acloud create && atest test-to-run
    
    现在,可以如下简化该命令:
    atest test-to-run --start-avd
    

  • 通过指定 acloud create 参数启动 AVD,并在新创建的该设备上运行测试。

    atest test-to-run --acloud-create "--build-id 6509363 --build-target aosp_cf_x86_phone-userdebug --branch aosp_master"
    

如需获取有关该参数的使用详情,请运行 acloud create --help

将选项传递给模块

Atest 能够将选项传递给模块。Atest 命令行中用于添加 TradeFed 命令行选项的简要格式如下

atest test-to-run -- [CUSTOM_ARGS]
[CUSTOM_ARGS] 应当遵循 TradeFed 命令行选项格式。

将测试模块选项传递给测试配置文件中定义的目标准备器或测试运行程序的示例:

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

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