FX 测试用户指南

fx test 是开发者入口点，用于在 fuchsia.git 的检出中运行测试。

本文档提供了面向开发者的指南，了解如何使用 fx test 进行树内测试。

基本用法

只需运行 fx test 即可开始使用：

fx test

这会执行以下操作：

1. 确定您当前 build 中包含的测试。
2. 根据选择条件选择一部分包含的测试。
3. 重新构建并重新发布这些测试。
4. 检查是否存在合适的 Fuchsia 设备来运行测试。
5. 同时，开始在该设备上运行测试并提供状态输出。
6. 写入一个日志文件，描述已发生的操作。

如果您未在 build 中添加任何测试，fx test 将退出。请尝试在 fx set 命令行中使用 fx set core.x64--with //src/diagnostics:tests，以添加一些测试作为示例。

基本概念

fx test 是一个测试执行器，这意味着它会提取可用测试的列表，并负责安排和观察其执行。此数据的来源为 tests.json。

tests.json 中列出的每个测试都是一个测试套件，其中每个测试可包含任意数量的测试用例。也就是说，测试套件是单个二进制文件或 Fuchsia 组件，它包含以特定于每个测试框架（例如 C++ TEST、Rust #[test]、Python unittest.TestCase）的方式定义的测试用例。枚举和执行设备上的测试用例由测试运行程序框架负责。

选择基本测试

fx test 支持使用命令行选项选择单个测试套件。这样，您就可以在 build 中包含大量测试，然后只执行其中一部分测试。

fx test 的任何非标志参数都是一个选择，与输入中的每个测试进行模糊匹配：

fx test archivist --dry

默认情况下，系统会搜索以下字段：

野战	说明
name	测试的全名。这是设备端测试和主机测试的测试二进制文件路径的组件网址。
label	测试的 build 标签。例如，//src/examples:my_test。
组件名称	仅用于设备端测试的组件清单（不包括 .cm）的名称。
软件包名称	仅适用于设备端测试的 Fuchsia 软件包的名称。

您可以通过列出前缀来选择源代码树中某个目录下的所有测试：

fx test //src/diagnostics/tests --dry

默认情况下，以上所有字段均匹配，但您可以使用 --package 或 --component 选择特定字段：

fx test --package archivist_unittests --dry

默认情况下，命令行上的多选会实现“包含或”运算。测试选择支持复合 AND 运算，如下所示：

fx test --package archivist --and unittests --dry

此命令会选择软件包与 archivist 匹配且任何字段与 unittests 匹配的所有测试。

如果您知道要执行的测试的确切名称，可以使用 --exact 标志仅选择该测试：

fx test --exact fuchsia-pkg://fuchsia.com/archivist-tests#meta/archivist-unittests.cm --dry

如果没有与您的选择匹配的测试，fx test 将尝试在源代码检出中以启发法的方式匹配测试，并建议包含这些测试的 fx set 参数：

$ fx test driver-tests --dry
...
For `driver-tests`, did you mean any of the following?

driver_tools_tests (91.67% similar)
    --with //src/devices/bin/driver_tools:driver_tools_tests
driver-runner-tests (90.96% similar)
    --with //src/devices/bin/driver_manager:driver-runner-tests
driver-inspect-test (90.96% similar)
    --with //src/devices/tests/driver-inspect-test:driver-inspect-test

然后，您可以向 build 添加必要的软件包。

基本测试输出

fx test 将其输出存储在日志文件中，以供日后分析。您可以使用 -pr/--previous 参数以文本形式查看此日志文件的摘要。例如，如需查看上次运行的测试日志，请执行以下操作：

$ fx test -pr log
previous-log-file.json.gz:

4 tests were run

[START first_test]
...
[END first_test]

如需查看用于处理之前的日志文件的选项的完整列表，请运行 fx test -pr help。

默认情况下，此命令会处理存储在 Fuchsia 输出目录中的最新日志，但您可以传递 --logpath 以选择特定日志。

此命令可以应对损坏或不完整的日志文件，因此即使您终止运行测试的 fx test 命令，此命令应该仍然有效。

基本测试调试

fx test 与 zxdb 集成，提供了一种简单简单的方法来调试测试失败情况，而无需重新编译任何内容。将 --break-on-failure 传递给 fx test 调用，使测试失败情况自动中断到调试程序：

$ fx test --break-on-failure rust_crasher_test.cm
...
⚠️  zxdb caught test failure in rust_crasher_test.cm, type `frame` to get started.
   14 LLVM_LIBC_FUNCTION(void, abort, ()) {
   15   for (;;) {
 ▶ 16     CRASH_WITH_UNIQUE_BACKTRACE();
   17     _zx_process_exit(ZX_TASK_RETCODE_EXCEPTION_KILL);
   18   }
══════════════════════════
 Invalid opcode exception
══════════════════════════
 Process 1 (koid=107752) thread 1 (koid=107754)
 Faulting instruction: 0x4159210ab797

🛑 process 1 __llvm_libc::__abort_impl__() • abort.cc:16
[zxdb] // Now you can debug why the test failed!

您还可以使用 --breakpoint=<location> 选项在代码中任意位置的特定位置设置断点。<location> 采用标准 zxdb 断点语法，通常是文件和行号或函数名称：

• --breakpoint=my_file.rs:123 在 my_file.rs 的第 123 行设置一个断点。
• --breakpoint=some_function 在 some_function 上设置断点。

请注意，此选项会导致测试的运行速度明显变慢，因为 zxdb 需要加载所有符号才能使测试能够安装断点。除 --test-filter 之外，强烈建议您仅使用此选项。

调试完测试失败后，您可以输入 quit、ctrl+d 或 detach * 以继续运行测试。请注意，如果有多个测试用例失败，此操作不会暂停，以便您也可以调试这些测试。如需详细了解如何调试并行发生的多个测试失败，请参阅调试测试。

配置选项

fx test 的可配置性非常强，fx test --help 中提供了完整的选项列表。

本部分介绍如何指定配置选项以及这些选项的含义。配置选项分为“实用程序”“构建”“测试选择”“执行”或“输出选项”。可以在命令行或配置文件中指定这些选项。

配置文件

fx test 的所有参数都在命令行中设置，但默认值可以按用户进行设置。如果您将名为 .fxtestrc 的文件放在 HOME 目录中，则该文件中的参数将是将来的 fx test 调用的新默认值。

例如：

# ~/.fxtestrc
# Lines starting with "#" are comments and ignored.
# The below config roughly matches the behavior of the old Dart-based `fx test`.

# Default parallel to 1.
--parallel 1

# Disable status output.
--no-status

# Print output for tests taking longer than 2 seconds.
--slow 2

上述文件将替换 --parallel 和 --status 标志的默认值，通常它们的默认值为 4 和 false。在调用 fx test 时，新的默认值可能仍会在命令行中被替换。

实用工具选项

实用程序选项会更改 fx test 的总体行为。

--dry 会执行“试运行”。fx test 会完成测试选择，但只会输出所选测试套件的列表，而不执行任何测试套件。

--list 在“列表模式”下运行 fx test。此命令不会执行测试，而是列出每个测试套件中的所有测试用例。 它会输出相应的命令行来运行每种情况。 请注意，这需要访问 Fuchsia 设备或模拟器，因为设备上的测试管理器会枚举这些用例。

-pr/--prev/--previous COMMAND 将处理先前执行 fx test 时的日志文件，并根据 COMMAND 的值输出信息。系统不会执行任何新的测试。此命令遵循 --logpath 来指定要读取的日志。

已实现以下 COMMAND：

• log 会输出日志文件中记录的每个测试的命令行和输出。
• help 会输出可用命令的摘要。

构建选项

默认情况下，fx test 会构建和更新所选的测试。这在运行 fx -i test 时非常有用，它会检测源目录的更改并在每次文件修改后重新调用 fx test。测试重新构建的工作原理如下（以内嵌方式列出替换项）。

• 所有选定的测试都是通过针对每次 fx test 调用调用 fx build <targets> 来重新构建。
  • 使用 --[no-]build 可切换此行为。
• 如果所选测试在 build 的“基础软件包”中（使用 fx set --with-base 指定），系统将构建 updates 软件包并执行 OTA。
  • 使用 --[no-]updateifinbase 可切换此行为。
  • 警告：以模拟器为目标平台时，OTA 将失败。

测试选择选项

以下选项会影响 fx test 选择哪些测试以及选择的应用方式。

--host 和 --device 分别仅选择主机或设备测试。这是一项全局设置，无法组合使用。

--[no-]e2e 用于控制是否运行端到端 (E2E) 测试。 默认情况下，E2E 测试不会运行，因为它们可能会使设备处于无效状态。--only-e2e 隐含 --e2e，并确保仅选择端到端测试。

分别在软件包名称或组件名称中选择 --package (-p) 和 --component (-c)。前面没有选择任何测试字段的名称。 --and (-a) 可以更改多项选择。例如：

fx test --package foo -a --component bar //src/other --and --package my-tests

上述命令行包含两个选择子句：

1. 软件包“foo”和组件“bar”（例如 fuchsia-pkg://fuchsia.com/foo#meta/bar.cm）。
2. 软件包“my-tests”和 //src/other。

系统会选择与上述任一子句匹配的测试。

默认情况下，测试选择使用 3 的 Damerau-Levenshtein 距离进行模糊匹配（例如“my_tset”将与“my-test”匹配）。--fuzzy <N> 可用于将此值替换为 N，其中 0 表示不进行模糊匹配。

如果没有与选择子句匹配的测试，系统会默认显示建议。您可以使用 --suggestions-count N 替换建议数量（默认为 6 个），也可以使用 --[no-]show-suggestions 停用或启用建议数量。

执行选项

测试以特定方式执行，以最大限度地提高吞吐量和稳定性，但此默认值的每个元素都可以被替换。测试按以下方式执行（以内嵌方式列出替换项）：

• 每个选定的测试都会按照它们在 tests.json 中显示的顺序执行
  • 使用 --random 可随机化此执行顺序。
• 所有选定的测试都会从上面有序列表的开头开始运行。
  • 使用 --offset N 跳过列表开头的 N 测试。默认值为 0。
  • 使用 --limit N 从偏移量运行最多 N 项测试。默认值为无上限。
• 最多可以并行运行 4 项测试，因此其中最多一项测试是“非封闭”测试（由 test-list.json 确定）。
  • 使用 --parallel N 可更改此默认值。--parallel 1 表示依次执行每个测试。
• 测试会一直运行，直到自行终止。
  • 使用 --timeout N 使每次测试最多等待 N 秒。
• 每个测试运行一次。
  • 使用 --count N 运行每个测试 N 次。
• 所有测试用例均从每个测试中运行。
  • 使用 --test-filter 可仅运行专门命名的测试用例。
• 系统会记录失败的测试，并继续执行下一个所选的测试。
  • 使用 --fail (-f) 可在第一次失败后终止所有测试。
• 如果发现严重级别更高的日志，在 tests.json 中指定最高日志级别的测试将失败。
  • 使用 --[no-]restrict-logs 可切换此行为。
• 测试组件会自行选择要发出的最低日志严重级别。
  • 使用 --min-severity-logs 可替换所有测试组件的此最小值。
• 使用 build 工件中的 Merkle 根哈希运行测试组件，这可确保 build 的最新版本已成功推送到目标并正在运行。
  • 使用 --[no-]use-package-hash 可切换此行为。
• 系统不会运行已停用的测试用例。
  • 无论如何，都需要使用 --also-run-disabled-tests 运行已停用的测试用例。
• 测试输出日志仅包含组件名称的最后一段，因此更便于查看。
  • 使用 --[no-]show-full-moniker-in-logs 可切换此行为。

• 失败的测试会在失败后终止，无需等待

  • 使用 --break-on-failure 通过 zxdb 捕获失败的测试。
  • 使用 --breakpoint=<location> 在特定 [位置][#basic-test-debugging]安装断点。

  请注意，使用 --breakpoint 选项会显著减慢测试速度。强烈建议仅将此选项与 --test-filter 结合使用。--break-on-failure 可以在许多测试中使用，而对性能的影响微乎其微。

• 测试的命令行参数完全由测试运行程序控制

  • 将 -- 附加到参数中，以将其余参数逐字传递给测试。例如：fx test foo -- --argument_for_test 会将 --argument_for_test 传递给测试本身。

• 主机测试会自动从用户环境中继承一组有限的环境变量

  • 使用 --env (-e) 向测试添加新的 KEY=VALUE 环境变量。此标志可以指定多次。

输出选项

fx test 适用于开发者用例，包含一个简单的终端界面，可在测试执行时显示测试状态。默认输出行为如下所示（以内嵌方式列出替换项）：

• 终端底部会显示状态显示窗口，它会自动更新以显示当前正在执行的操作。
  • 使用 --[no-]status 可切换状态显示。
  • 使用 --status-lines N 更改状态输出行的数量。
  • 使用 --status-delay N 更改刷新率（默认值为 0.033 或约 30 Hz）。如果终端运行缓慢，您可能需要将其更改为 0.5 或 1。
• 输出采用 ANSI 终端颜色设置样式。
  • 使用 --[no-]style 可切换此行为。
  • 使用 --simple 作为 --no-style --no-status 的简写形式。
• 系统仅针对失败的测试显示测试输出。
  • 使用 --output (-o) 显示所有测试输出（与 --parallel 1 结合使用可防止交错）。
  • 使用 --no-output 明确隐藏输出，例如替换配置中设置的 --output。
  • 使用 --slow N (-s N) 可以仅显示执行时间超过 N 秒的测试套件的输出。
• 日志将写入 fx status 指定的 build 目录下带有时间戳的 .json.gz 文件。
  • 使用 --[no-]log 完全切换日志记录。
  • 使用 --logpath 更改日志的输出路径。
• 测试工件不会流式传输到设备之外。
  • 使用 --ffx-output-directory 指定一个目录，以便以 ffx test 输出格式流式传输工件。
• 禁止使用调试打印。
  • 使用 --verbose (-v) 将调试信息输出到控制台。这些数据极其冗长，仅可用于调试 fx test 本身。extremely

日志格式

fx test 旨在通过将每个用户可见的输出表示为一个在执行期间记录到文件的“事件”来支持外部工具。

日志文件使用 gzip 进行压缩。解压缩后的文件中的每一行都是一个代表一个事件的 JSON 对象。事件架构当前在此 Python 文件中定义。

格式稳定后，可以构建交互式查看器和转换为其他格式（例如构建事件协议）的转换器。