从命令行测试

本文档介绍了如何直接从命令行运行测试。本文档假设您已经了解如何创建 Android 应用以及为您的应用编写测试。有关如何为您的应用构建测试的更多信息，请参阅 在 Android 上测试应用。

当您使用 Gradle 构建系统构建应用时，Android Gradle 插件 允许您使用命令行从 Gradle 项目运行测试。为了获得更细粒度的控制，您可以选择通过 Android 调试桥 (adb) shell 运行测试。这在 持续集成 环境中运行测试时非常有用。

要了解如何使用 Gradle 为您管理的虚拟设备从命令行运行自动化的 Instrumentation 测试，请参阅 使用 Gradle 托管设备扩展测试。

使用 Gradle 运行测试

Android Gradle 插件允许您使用命令行从 Gradle 项目运行测试。

下表总结了如何使用 Gradle 运行测试

表 1. 使用 Gradle 运行测试的不同方法

单元测试类型 运行命令 测试结果位置
本地单元测试 运行 test 任务

./gradlew test
HTML 测试结果文件
path_to_your_project/module_name/build/reports/tests/ 目录。

XML 测试结果文件
path_to_your_project/module_name/build/test-results/ 目录。
Instrumentation 单元测试 运行 connectedAndroidTest 任务

./gradlew connectedAndroidTest
HTML 测试结果文件
path_to_your_project/module_name/build/reports/androidTests/connected/ 目录。

XML 测试结果文件
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ 目录。

Gradle 支持 任务名称缩写。例如，您可以通过输入以下命令来启动 connectedAndroidTest 任务

./gradlew cAT

您还可以选择运行 Gradle 任务 check 和 connectedCheck。这些任务分别运行您的本地或 Instrumentation 测试，但也包含其他 Gradle 插件添加的其他检查。

在模块上运行测试

test 和 connectedAndroidTest 任务在项目中的每个模块上运行测试。您可以通过在 test 或 connectedAndroidTest 任务前加上模块名称和冒号 (:) 来在特定模块上运行测试。例如，以下命令仅为 mylibrary 模块运行 Instrumentation 测试

./gradlew mylibrary:connectedAndroidTest

在构建变体上运行测试

test 和 connectedAndroidTest 任务在项目中的每个 构建变体 上运行测试。您可以使用以下语法定位特定的构建变体

  • 对于本地单元测试
    ./gradlew testVariantNameUnitTest
  • 对于 Instrumentation 测试
    ./gradlew connectedVariantNameAndroidTest

运行特定的测试方法或类

在运行本地单元测试时，Gradle 允许您使用 --tests 标志来定位特定的测试。例如，以下命令仅为指定的构建变体运行 sampleTestMethod 测试。要详细了解如何使用 --tests 标志，请阅读 Gradle 关于 测试过滤 的文档。


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

使用 adb 运行测试

当您使用 Android 调试桥 (adb) 从命令行运行测试时，与其他任何方法相比，您可以选择要运行的测试的选项更多。您可以选择单个测试方法、根据自定义注释过滤测试或指定测试选项。由于测试运行完全由命令行控制，因此您可以通过各种方式使用 shell 脚本自定义测试。

要从命令行运行测试，请运行 adb shell 以在您的设备或模拟器上启动命令行 shell。在该 shell 中，您可以使用 am 命令与 活动管理器 交互，并使用其 instrument 子命令运行测试。

作为快捷方式，您可以启动 adb shell、调用 am instrument 并在一行输入中指定命令行标志。shell 在设备或模拟器上打开，运行您的测试，生成输出，然后返回到您计算机上的命令行。

要使用 am instrument 运行测试

  1. 构建 或重建您的主应用程序和测试包。
  2. 安装 您的测试包和主应用程序 Android 包文件 (APK 文件) 到您当前的 Android 设备或模拟器。

  3. 在命令行中，输入

    adb shell am instrument -w <test_package_name>/<runner_class>

    其中 <test_package_name> 是测试应用程序的 Android 包名称，<runner_class> 是您正在使用的 Android 测试运行程序类的名称。Android 包名称是测试包清单文件 (AndroidManifest.xml) 中清单元素的 package 属性的值。

    Android 测试运行程序类通常是 AndroidJUnitRunner

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

您的测试结果显示在 STDOUT 中。

am instrument 标志

要查找与 am instrument 命令一起使用的所有标志的列表，请运行 adb shell am help。下表描述了一些重要的标志

表 2. 重要的 am instrument 标志

标志 值 描述
-w (无) 强制 am instrument 在自身终止之前等待 Instrumentation 终止。这将使 shell 保持打开状态，直到测试完成。此标志是查看测试结果所必需的。
-r (无) 以原始格式输出结果。当您想要收集性能测量结果但不想将其格式化为测试结果时，请使用此标志。此标志旨在与标志 -e perf true（在 am instrument 选项 部分中记录）一起使用。
-e <test_options> 以键值对的形式提供测试选项。am instrument 工具使用其 onCreate() 方法将这些选项传递给指定的 Instrumentation 类。您可以指定多次 -e <test_options>。键和值在 am instrument 选项 部分中进行了描述。您只能将这些键值对与 AndroidJUnitRunner 或与 InstrumentationTestRunner 及其子类一起使用。与任何其他类一起使用它们无效。
--no-hidden-api-checks (无) 禁用对隐藏 API 使用的限制。有关隐藏 API 的更多信息以及这如何影响您的应用，请阅读 对非 SDK 接口的限制。

am instrument 选项

am instrument 工具以键值对的形式将测试选项传递给 AndroidJUnitRunner 或 InstrumentationTestRunner，使用 -e 标志，语法如下

-e <key> <value>

某些键接受多个值。您可以在逗号分隔的列表中指定多个值。例如，此 AndroidJUnitRunner 调用为 package 键提供了多个值

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

下表列出了您可以与测试运行程序一起使用的键值对

表 3. 与测试运行程序一起使用的 -e 标志键值对

键 值 描述
package <Java_package_name> 测试应用程序中某个包的完全限定的 Java 包名称。使用此包名称的任何测试用例类都将执行。请注意，这不是 Android 包名称；测试包具有单个 Android 包名称，但可能在其内部包含多个 Java 包。
class <class_name> 某个测试用例类的完全限定的 Java 类名称。仅执行此测试用例类。
<class_name>#方法名称 一个完全限定的测试用例类名称及其方法之一。仅执行此方法。请注意类名称和方法名称之间的井号 (#)。
func true 运行扩展 InstrumentationTestCase 的所有测试类。
unit true 运行所有不扩展 InstrumentationTestCase 或 PerformanceTestCase 的测试类。
size [small | medium | large] 运行由大小注释的测试方法。注释为 @SmallTest、@MediumTest 和 @LargeTest。
perf true 运行实现 PerformanceTestCase 的所有测试类。当您使用此选项时，请为 am instrument 指定 -r 标志，以便输出保持原始格式，而不是重新格式化为测试结果。
debug true 在调试模式下运行测试。
log true 加载并记录所有指定的测试，但不运行它们。测试信息显示在 STDOUT 中。使用此方法验证其他过滤器和测试规范的组合。
emma true 运行 EMMA 代码覆盖率分析并将输出写入设备上的 /data/<app_package>/coverage.ec。要覆盖文件位置，请使用以下条目中描述的 coverageFile 键。

注意：此选项需要测试应用程序的 EMMA 检测构建，您可以使用 coverage 目标生成该构建。
coverageFile <filename> 覆盖设备上 EMMA 覆盖文件的默认位置。将此值指定为 UNIX 格式的路径和文件名。默认文件名在 emma 键的条目中进行了描述。

使用 -e 标志时，请注意以下事项

  • 当使用am instrument 调用测试时，它会使用包含键值对的 Bundle 来调用 onCreate(Bundle)。
  • package 键的优先级高于 class 键。如果您指定了一个包，然后在该包中单独指定了一个类，Android 将运行包中的所有测试，并忽略类键。
  • func 键和 unit 键是互斥的。

使用示例

以下部分提供了使用 am instrument 运行测试的示例。它们基于以下结构

  • 测试包的 Android 包名为 com.android.demo.app.tests。
  • 两个 Instrumentation 测试类
    • TestClass1，其中包含测试方法 testMethod1。
    • TestClass2，其中包含测试方法 testMethod2 和 testMethod3。
  • 测试运行器是 AndroidJUnitRunner。

运行整个测试包

要运行测试包中的所有测试类，请输入

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

运行测试用例类中的所有测试

要运行类 TestClass1 中的所有测试，请输入

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

选择测试子集

要运行 TestClass1 类中的所有测试以及 TestClass2 中的 testMethod3 方法，请输入

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

您可以在 AndroidJUnitRunner API 参考中找到更多用例。