从命令行测试

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

当您使用 Gradle 构建系统构建应用时，Android Gradle 插件允许您使用命令行从 Gradle 项目运行测试。为了更精细地控制，您可以选择通过 Android 调试桥 (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/` 目录。
插桩单元测试	运行 `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。这些任务分别运行您的本地测试或插桩测试，但会包含其他 Gradle 插件添加的其他检查。

在模块上运行测试

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

./gradlew mylibrary:connectedAndroidTest

在构建变体上运行测试

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

对于本地单元测试
```
./gradlew testVariantNameUnitTest
```

对于插桩测试

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

构建或重新构建您的主应用和测试软件包。
将您的测试软件包和主应用 Android 软件包文件 (APK 文件) 安装到当前的 Android 设备或模拟器上。
在命令行中，输入
```
adb shell am instrument -w <test_package_name>/<runner_class>
```
其中 <test_package_name> 是您的测试应用的 Android 软件包名称，<runner_class> 是您正在使用的 Android 测试运行器类的名称。Android 软件包名称是您测试软件包的清单文件 (AndroidManifest.xml) 中 manifest 元素的 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` 等待插桩终止后自身才终止。这会使 shell 保持打开状态，直到测试完成。此标志是查看测试结果所必需的。
`-r`	(无)	以原始格式输出结果。当您希望收集性能测量值，使其不被格式化为测试结果时，请使用此标志。此标志设计用于配合 `-e perf true` 标志（在am instrument 选项部分中描述）使用。
`-e`	`<test_options>`	以键值对形式提供测试选项。`am instrument` 工具使用其 `onCreate()` 方法将这些选项传递给指定的插桩类。您可以指定多个 `-e <test_options>`。键和值在am instrument 选项部分中描述。您只能将这些键值对与 `AndroidJUnitRunner` 或 `InstrumentationTestRunner` 及其子类一起使用。与任何其他类一起使用将无效。
`--no-hidden-api-checks`	(无)	禁用对使用隐藏 API 的限制。有关什么是隐藏 API 以及这如何影响您的应用的更多信息，请阅读非 SDK 接口限制。

am instrument 选项

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

-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`	`<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 插桩构建，您可以使用 `coverage` 目标生成。
`coverageFile`	`<filename>`	覆盖设备上 EMMA 覆盖率文件的默认位置。将此值指定为 UNIX 格式的路径和文件名。默认文件名在 `emma` 键的条目中描述。

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

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

使用示例

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

测试软件包的 Android 软件包名称为 com.android.demo.app.tests。
两个插桩测试类
- 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 参考中找到更多用例。