FIDL 测试和 GN

本文档旨在标准化在 GN 构建系统中定义和整理 FIDL 测试的方式，同时实现以下目标：

  • 命名保持一致。如果 Rust 使用 fx test fidl_rust_conformance_tests，则 Go 应使用 fx test fidl_go_conformance_tests。一致且可预测的命名可提供更好的开发者体验。
  • 运行所需内容。测试工作流应能让您轻松运行单个测试组件，而无需构建或运行任何额外内容。
  • 在主机上运行。如果可能，测试应支持在主机（非 Fuchsia）上运行，这样编辑-构建-运行周期通常会快得多。
  • 遵循最佳实践。我们应遵循有关使用 fx test、构建组件等的 Fuchsia 最佳实践。

术语

本文档使用以下术语：

  • 目标：BUILD.gn 文件中定义的 GN 目标
  • 工具链：请参阅 fx gn help toolchain
  • 宿主：开发者的平台，具体为 Linux 或 Mac
  • 设备：Fuchsia 平台，可以是实体设备，也可以是模拟设备（即 qemu）
  • 软件包：一种 Fuchsia 软件包；Fuchsia 中的分发单元
  • 组件：Fuchsia 组件；Fuchsia 中的可执行软件单元

命名

通用准则：

  • 请使用下划线，而不是连字符。
  • 名称以复数形式 _tests 而不是单数形式 _test 结尾。
  • 为软件包、组件和二进制文件使用完整、描述性强且唯一的名称。

最后一点是指，最好使用 fidl_rust_conformance_tests 等全名，而不是 conformance_tests 等上下文名称。在目录、软件包、组件和二进制文件级层重复使用“fidl”和“rust”似乎过于冗长且多余。但事实是，这些名称必须是唯一的，最好以一致的方式确保其唯一性，而不是记住 fidl-bindings-test 用于 Dart、fidl-test 用于 C 等奇怪的规则。

名称应使用以下方案，并用下划线连接各个部分：

工具 [ 绑定 ] [ 类别 [ 子类别 ] ] 测试

其中，工具是以下项之一：

  • fidl：FIDL 运行时支持
  • fidlc：FIDL 编译器前端
  • fidlgen：FIDL 编译器后端
  • gidl、measure_tape 等：其他工具

其他部分包括：

  • 绑定
    • c、cpp、cpp_wire、hlcpp、rust、go、dart 之一
  • 类别、子类别
    • 示例类别：一致性、类型、解析器、库
    • 请勿使用：前端、后端、绑定（工具会区分这些）

层次结构

每个定义测试的 BUILD.gn 文件都应包含一个 "tests" 组：

group("tests") {
  testonly = true
  deps = [ ... ]  # not public_deps
}

如果目录以“tests”结尾，并且 BUILD.gn 文件仅定义测试目标，则该组应改为与目录名称匹配。例如，foo_tests/BUILD.gn 可以使用 group("foo_tests")。这样便可使用 GN 标签简写形式 //path/to/foo_tests，相当于 //path/to/foo_tests:foo_tests。

这些组会汇总到父目录的 BUILD.gn 文件中的“tests”组中。根“测试”组（针对代码库的某个部分，例如 src/lib/fidl/BUILD.gn）应包含在 bundles/fidl/BUILD.gn 中。这使得 fx set ... --with //bundles/fidl:tests 能够在 build 中包含所有 FIDL 测试。（测试也会在 CQ 中运行，因为 //bundles/buildbot/core 包含 //bundles/fidl:tests。）

二进制名称

通常，测试二进制文件的名称基于目标名称。例如，test("some_tests") { ... } 目标会生成 some_tests 二进制文件。不过，对于单个测试，您通常需要多个具有唯一名称的目标（源集、组件、软件包等）。因此，本文档中的示例使用 some_tests_bin 等目标名称，并使用 output_name 参数替换二进制名称：

test("some_tests_bin") {
  output_name = "some_tests"
  ...
}

此方法也适用于 rustc_test、go_test 等。

设备测试

假设我们有一个 :fidl_foo_tests_bin 目标，该目标会生成 fidl_foo_tests 二进制文件。如需将其封装在软件包中，请使用 fuchsia_unittest_package：

import("//build/components.gni")

fuchsia_unittest_package("fidl_foo_tests") {
  deps = [ ":fidl_foo_tests_bin" ]
}

现在，我们可以使用 fx test fidl_foo_tests 按软件包名称或组件名称（两者相同）运行测试。

为每个测试使用单独的软件包。如果无关的测试组件捆绑在一个软件包中，那么运行其中一个测试会导致整个软件包被重新构建。只有当多个测试组件需要一起测试时，您才应将它们捆绑在一个软件包中，例如客户端和服务器集成测试。如需查看示例，请参阅复杂拓扑和集成测试。

如果您的测试需要超出 fuchsia_unittest_component 默认值的任何组件功能、服务等，您必须编写组件清单文件：

# BUILD.gn
import("//build/components.gni")

fuchsia_unittest_package("fidl_foo_tests") {
  manifest = "meta/fidl_foo_tests.cml"
  deps = [ ":fidl_foo_tests_bin" ]
}

# meta/fidl_foo_tests.cml
{
    program: {
        "binary": "bin/fidl_foo_tests"
    },
    use: [
      {
        protocol: [
          "fuchsia.logger.LogSink",   # some example services
          "fuchsia.process.Launcher"
        ]
      }
    ]
}

如需详细了解软件包和组件模板，请参阅构建组件。

主机测试

假设我们有一个 :fidl_bar_tests_bin 目标，该目标会生成 fidl_bar_tests 二进制文件。我们必须确保 GN 在达到该目标时处于 $host_toolchain 中，否则它会尝试为 Fuchsia 构建 GN：

groups("tests") {
  testonly = true
  deps = [ ":fidl_bar_tests_bin($host_toolchain)" ]
}

（始终将 ($host_toolchain) 放在 BUILD.gn 文件的 tests 组中，而不是放在 //bundles/fidl:tests 中。）

这将创建一个名为 host_x64/fidl_bar_tests 的 test_spec 条目，该条目最终会出现在 out/default/tests.json 中：

{
  "command": [ "host_x64/fidl_bar_tests", "--test.timeout", "5m" ],
  "cpu": "x64",
  "label": "//PATH/TO/BAR:fidl_bar_tests_bin(//build/toolchain:host_x64)",
  "name": "host_x64/fidl_bar_tests",
  "os": "linux",
  "path": "host_x64/fidl_bar_tests",
  "runtime_deps": "host_x64/gen/PATH/TO/BAR/fidl_bar_tests_bin.deps.json"
}

运行 fx test fidl_bar_tests 之所以有效，是因为 tests.json 中有“name”字段。

主机/设备测试

在主机和设备上运行的测试分为两类。在第一类中，测试目标只需在任一工具链下构建即可。例如：

import("//build/components.gni")

rustc_test("fidl_rust_conformance_tests_bin") {
  output_name = "fidl_rust_conformance_tests"              # host test name
  ...
}

fuchsia_unittest_package("fidl_rust_conformance_tests") {  # device test name
  deps = [ ":fidl_rust_conformance_tests_bin" ]
}

group("tests") {
  testonly = true
  deps = [
    ":fidl_rust_conformance_tests_bin($host_toolchain)",
    ":fidl_rust_conformance_tests",
  ]
}

现在，我们可以通过以下两种方式运行测试：

  • 在设备上：fx test fidl_rust_conformance_tests --device
  • 在主机上：fx test fidl_rust_conformance_tests --host

在第二类中，设备测试和主机测试共享源代码，但它们足够不同，必须通过单独的目标进行定义。这需要将宿主测试定义封装在 if (is_host) { ... } 中，以防止 GN 抱怨多个目标生成相同的输出。例如：

import("//build/components.gni")

source_set("conformance_test_sources") {
  ...
}

test("fidl_hlcpp_conformance_tests_bin") {
  output_name = "fidl_hlcpp_conformance_tests"
  ...
  deps = [
    ":conformance_test_sources",
    ...
  ]
}

if (is_host) {
  test("fidl_hlcpp_conformance_tests_bin_host") {
    output_name = "fidl_hlcpp_conformance_tests"            # host test name
    ...
    deps = [
      ":conformance_test_sources",
      ...
    ]
  }
}

fuchsia_unittest_package("fidl_hlcpp_conformance_tests") {  # device test name
  deps = [ ":fidl_hlcpp_conformance_tests_bin" ]
}

group("tests") {
  testonly = true
  deps = [
    ":fidl_hlcpp_conformance_tests_bin_host($host_toolchain)",
    ":fidl_hlcpp_conformance_tests",
  ]
}

现在，我们可以通过以下两种方式运行测试：

  • 在设备上：fx test fidl_hlcpp_conformance_tests --device
  • 在主机上：fx test fidl_hlcpp_conformance_tests --host

Rust 单元测试

Rust 库可以按如下方式定义：

rustc_library("baz") {
  with_unit_tests = true
  ...
}

这会自动创建一个用于构建 baz_lib_test 二进制文件的 baz_test 目标。请勿使用此方法，原因有二：

  1. 命名准则要求使用 _tests 后缀，而不是 _test。
  2. 这可能会造成混淆，并且未来可能会被弃用。

请勿使用 with_unit_tests，而是编写一个单独的 rustc_test 目标，并为其指定适当的名称：

rustc_library("baz") {
  ...
}

rustc_test("fidl_baz_tests") {
  ...
}

分组

假设我们有以下测试结构：

  • FIDL Rust
    • 设备
      • 一致性
      • 集成
    • 主机
      • 一致性

我们应该为叶节点设置测试目标：

  • fx test fidl_rust_conformance_tests
  • fx test fidl_rust_integration_tests

我们不应为运行各种测试子集创建额外的软件包。使用 fx test，我们已经可以

  • 运行所有测试：fx test //path/to/fidl/rust
  • 运行所有设备测试：fx test //path/to/fidl/rust --device
  • 运行所有主机测试：fx test //path/to/fidl/rust --host

参考文档