FIDL 测试和 GN

本文档标准化了我们在 GN 构建系统中定义和组织 FIDL 测试的方式，并遵循以下目标：

  • 名称保持一致。如果 Rust 使用 fx test fidl_rust_conformance_tests，则 Go 应使用 fx test fidl_go_conformance_tests。一致且可预测的命名有助于提升开发者体验。
  • 运行您需要的映像。测试工作流应该让单个测试组件能够轻松运行，而无需构建或运行任何额外的组件。
  • 在主机上运行。测试应尽可能支持在主机（非紫红色）上运行，在主机（修改-构建-运行）的周期内通常要快得多。
  • 遵循最佳做法。我们应遵循有关使用 fx test、构建组件等方面的 Fuchsia 最佳实践。

术语

本文档使用以下术语：

  • target：在 BUILD.gn 文件中定义的 GN 目标
  • toolchain：请参阅 fx gn help toolchain
  • host：开发者的平台，具体为 linux 或 mac
  • device：Fuchsia 平台，物理或模拟（如 qemu）
  • package：紫红色软件包；紫红色的分发单位
  • 组件：紫红色组件；是紫红色的可执行软件的单元

命名

通用准则：

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

最后一点表示优先使用全名（例如 fidl_rust_conformance_tests），而不是 conformance_tests 等上下文名称。在目录、软件包、组件和二进制文件级别重复使用“fidl”和“rust”可能会显得冗长而又多余。但实际上，这些名称必须是唯一的，最好以一致的方式使它们具有唯一性，而不是记住奇怪的规则，例如 fidl-bindings-test 适用于 Dart，fidl-test 适用于 C。

名称应使用以下架构，以下划线连接部分：

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

其中 tool 为以下项之一：

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

其他部分是：

  • 绑定
    • 可以是 c、cpp、cpp_wire、hlcpp、rust、go 和 dart
  • category、subcategory
    • 类别示例：conformance、types、parser、lib
    • 请勿使用：frontend、Backend、bindings（用于区分这些内容的工具）

层次结构

每个定义测试的 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 文件的“测试”组中。根“测试”组（针对代码库的某些部分，例如 src/lib/fidl/BUILD.gn）应包含在 bundle/fidl/BUILD.gn 中。这样一来，fx set ... --with //bundles/fidl:tests 便可以在 build 中包含所有 FIDL 测试。（由于 //bundles/buildbot/core 包含 //bundles/fidl:tests，因此也会在 CQ 中运行这些测试。）

二进制文件名称

通常，测试二进制文件名称基于目标名称。例如，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. 该方法可能会让人感到困惑，并且将来可能会被弃用。

请单独编写一个采用适当名称的 rustc_test 目标，而不是 with_unit_tests：

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

参考编号