从命令行测试

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

使用 Gradle 构建系统构建应用时，Android Gradle 插件 允许您使用命令行从 Gradle 项目运行测试。为了实现更精细的控制，您可以选择通过 Android Debug Bridge (adb) shell 运行测试。这在 持续集成 环境中运行测试时很有用。

要了解如何使用 Gradle 为您管理的虚拟设备从命令行运行自动化的检测测试，请参阅 使用 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/ 目录。
Instrumented 单元测试 运行 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>#method 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 Instrumentation 构建，您可以使用 coverage 目标来生成它。
coverageFile <filename> 覆盖设备上 EMMA 覆盖文件的默认位置。将此值指定为 UNIX 格式的路径和文件名。默认文件名在 emma 键的条目中进行了介绍。

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

  • am instrument 会使用包含键值对的 Bundle 调用 onCreate(Bundle)。
  • package 键优先于 class 键。如果您指定了一个包，然后单独指定了该包中的一个类，Android 会运行包中的所有测试，并忽略 class 键。
  • 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 参考中找到更多用例。