Atest

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

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

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

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

设置您的环境

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

设置环境变量

按照打包编译脚本规则Soong 设置 test_suite,或为 Make 设置 LOCAL_COMPATIBILITY_SUITE。

1. 运行 envsetup.sh

从 Android 源代码检出的根目录处,运行:

source build/envsetup.sh

2. 运行 lunch

运行 $ lunch 命令以显示受支持设备菜单。找到相应设备并运行该命令。

例如,如果您已连接 ARM 设备,请运行以下命令:

lunch aosp_arm64-eng

这会设置运行 Atest 所需的各种环境变量,并将 Atest 命令添加到您的 $PATH

基本用法

Atest 命令采用以下形式:

atest [optional-arguments] test-to-run

可选参数

您可以在 Atest 命令中使用以下可选参数。

选项 长选项 说明
-b --build 构建测试目标。
-i --install 在设备上安装测试软件工件 (APK)。
-t --test 运行测试。
-s --serial 在指定设备上运行测试。一次可以测试一台设备。
-d --disable-teardown 停用测试拆解和清理。
--info 显示指定目标的相关信息并退出。
--dry-run --info 的同义词。
-m --rebuild-module-info 强制重建 module-info.json 文件。
-w --wait-for-debugger 在执行之前等待调试程序。仅用于插桩测试。
-v --verbose 显示 DEBUG 级别日志记录。
--generate-baseline 生成基准指标,默认情况下运行 5 次迭代。
--generate-new-metrics 生成新指标,默认情况下运行 5 次迭代。
--detect-regression 运行回归检测算法。
--[CUSTOM_ARGS] 为测试运行器指定自定义参数。
-a --all-abi 针对所有可用的设备架构运行测试。
-h --help 显示帮助消息并退出。
--host 在没有设备的情况下在主机上完全运行测试。
(注意:使用 --host 运行需要设备的主机测试将失败)。

要详细了解 -b-i-t,请参阅指定步骤:编译、安装或运行

要运行的测试

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

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

以下是一些示例:

atest FrameworksServicesTests
atest example/reboot
atest FrameworksServicesTests CtsJankDeviceTestCases
atest FrameworksServicesTests:ScreenDecorWindowTests

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

标识测试

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

模块名称

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

示例:

atest FrameworksServicesTests
atest CtsJankDeviceTestCases

Module:Class

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

示例:

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

类名称

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

示例:

atest ScreenDecorWindowTests
atest CtsDeviceJankUi

建议尽可能使用 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 文件的路径来运行该类。同时支持相对路径和绝对路径。

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

  1. 从 android repo-root 运行模块:

    atest cts/tests/jank
    
  2. 从 android repo-root/cts/tests/jank 运行:

    atest .
    

示例:通过路径运行 CtsJankDeviceTestCases 模块内的特定类。从 android repo-root 运行:

atest cts/tests/jank/src/android/jank/cts/ui/CtsDeviceJankUi.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/servicestests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange
    

可以从不同的类和模块运行多个方法:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

运行多个类

要运行多个类,请使用空格将这些类分隔开,如同运行多个测试。Atest 可有效地构建和运行类,因此指定模块中的一部分类可以提高性能(与运行整个模块相比)。

示例:

  • 同一模块中的两个类:

    atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests
    
  • 不同模块中的两个类:

    atest FrameworksServicesTests:ScreenDecorWindowTests CtsJankDeviceTestCases:CtsDeviceJankUi
    

运行原生测试

Atest 可以运行原生测试。

示例:

  • 输入测试:

    atest -a libinput_tests inputflinger_tests
    

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

检测指标回归

您可以生成打补丁前指标或打补丁后指标,而无需运行回归检测。您可以指定迭代次数,但默认值为 5。

示例:

atest test-to-run --generate-baseline [optional-iteration]
atest test-to-run --generate-new-metrics [optional-iteration]

可以通过三种方法运行本地回归检测:

  1. 生成基准(打补丁前)指标并将其放在文件夹中。Atest 按照指定的迭代次数运行测试,生成打补丁后指标,并将这些指标与现有指标进行比较。

    例如:

    atest test-to-run --detect-regression /path/to/baseline --generate-new-metrics [optional-iteration]
    
  2. 使用包含以前生成的打补丁后指标的文件夹,Atest 会运行测试并进行 n 次迭代,生成一组新的打补丁前指标,并将这些指标与所提供的那些指标进行比较。

    例如:

    atest test-to-run --detect-regression /path/to/new --generate-baseline [optional-iteration]
    
  3. 使用同时包含打补丁前指标和打补丁后指标的两个文件夹,Atest 会运行回归检测算法而不进行任何测试。

    例如:

    atest --detect-regression /path/to/baseline /path/to/new