robots: noindex
ffx test run 命令可以在 Fuchsia 设备上运行测试，并收集测试结果和诊断信息。
概念
ffx test run 命令会执行与 Fuchsia 测试运行程序框架集成的测试，该框架允许在 Fuchsia 组件中定义和实现测试用例。
如需在 Fuchsia 设备上运行测试组件，需要执行以下步骤：
- 将代码、组件和软件包定义编译为 Fuchsia 软件包。
- 使软件包可供目标设备使用。
- 在目标设备上运行测试组件。
ffx test 命令仅处理第 3 步。第 1 步和第 2 步本质上需要了解构建系统，而 ffx test 的设计明确不依赖于构建系统。
图 1. 一张流程图，显示了 ffx test 如何与其他用于编译和运行测试的工具配合使用。
ffx test 命令旨在用作被其他工具调用的较低级别工具，这些工具通常运行特定于构建系统或开发环境的测试。本页面记录的工作流主要适用于使用此类高级工具的开发者。如果您是测试作者，并且想要了解如何在特定项目中运行测试，请尝试查看项目代码库中的文档。如需在 Fuchsia 源代码检出 (fuchsia.git) 中运行测试，请参阅 fx test 文档。
不过，在极少数情况下，您可能需要直接调用 ffx test，才能使用高级工具中不提供的精细选项。此外，项目可能需要支持 ffx test 不支持的其他类型的测试，例如主机测试。高级测试脚本会直接处理这些问题，或将责任委托给其他工具。例如，fx test 用于 Fuchsia SDK 中的 fuchsia.git 和 bazel test 开发。
运行测试组件
如需在目标设备上运行测试组件，请运行以下命令：
ffx test run TEST_COMPONENT_URL
将 TEST_COMPONENT_URL 替换为目标测试组件网址。
以下示例命令会在目标设备上的 example.cm 组件中运行测试：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm
使用过滤条件运行特定测试用例
如需在测试组件中选择性运行测试用例，请运行以下命令：
ffx test run TEST_COMPONENT_URL --test-filter FILTERS
请替换以下内容：
- TEST_COMPONENT_URL - 目标测试组件网址。
- FILTERS - 用于匹配测试用例的模式。
--test-filter 选项中提供的过滤条件将根据 glob 模式进行匹配。系统只会运行与至少一个模式匹配的测试用例。例如，假设某个套件包含测试用例 Foo.Test1、Foo.Test2、Bar.Test1 和 Bar.Test2，则以下命令仅执行 Foo.Test1 和 Foo.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter Foo.*
可以通过在前面附加 - 来指定否定过滤条件。指定否定过滤条件后，系统会排除与否定过滤条件匹配的测试用例。例如，对于上述套件，下面的命令仅执行 Bar.Test1 和 Bar.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter -Foo.*
可以多次指定 --test-filter 选项。多个过滤器的行为如下所示：
- 如果未指定过滤条件，系统会运行所有测试用例。
- 如果仅指定了正过滤条件，则系统会运行与至少一个过滤条件匹配的测试用例。
- 如果仅指定了否定过滤条件，系统将不会运行与任何过滤条件都不匹配的测试用例。
- 同时指定正向过滤条件和反向过滤条件时，系统会运行与至少一个正向过滤条件匹配但与任何反向过滤条件都不匹配的测试用例。
使用与上面相同的套件，以下示例命令仅会执行 Foo.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter Foo.* --test-filter -*.Test1
使用参数运行测试
如需将参数传递给测试组件中的测试，请运行以下命令：
ffx test run TEST_COMPONENT_URL -- ARGS
请替换以下内容：
- TEST_COMPONENT_URL - 目标测试组件网址。
- ARGS - 要传递给测试的参数。
以下示例命令会将参数 hello 和 1234 直接传递给测试：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm -- hello 1234
运行测试并存储结构化结果
ffx test run 支持以机器可读格式输出和存储测试结果，该格式适合供其他工具使用（如需了解架构的详细信息，请参阅测试输出格式）。
如需在运行测试后存储结构化测试结果，请运行以下命令：
ffx test run TEST_COMPONENT_URL --output-directory DIR
请替换以下内容：
- TEST_COMPONENT_URL - 目标测试组件网址。
- DIR - 用于存储结构化测试结果的目录。
以下示例命令会将输出存储在 /tmp/ffx-out 目录中：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --output-directory /tmp/ffx-out
附录
返回代码
测试成功运行时，ffx test run 会返回零；如果失败，则会返回非零值。ffx test run 支持多种特殊错误代码：
| 名称 | 退出代码 | 说明 |
|---|---|---|
| 设置失败 | 28 | 未能连接到目标设备上的所需协议 |
| 已超时 | 21 | 由于超时，测试执行失败 |
中断信号
传递 SIGINT（通常通过在终端中按 Ctrl+C 来完成）后，ffx test run 会尝试优雅地停止正在进行的测试并存储结果。
实验功能
ffx test run 支持许多实验性功能。这些功能可能会发生重大更改或被移除。如需使用实验性功能，您需要通过将相应的 ffx config 字段设置为 true 来选择启用。如需了解可用的实验性功能以及如何选择启用，请参阅 ffx test run --help。