此页面由 Cloud Translation API 翻译。

CTF 用户指南

本用户指南全面介绍了兼容性测试适用于 Fuchsia (CTF)，一种用于冻结版本分支上工件的机制并将其加载到 main 分支上，以用于测试目的。

CTF 最常见的用例是冻结版本分支上的测试，然后，在 CI/CQ 中针对 main 分支上的组件运行该测试。这个防止因向后不兼容的更改而破坏预构建的客户端。

如需从整体上详细了解 CTF，请参阅概览和动机文档。

基本用法

本部分介绍了如何使用 CTF 以及如何处理常见场景。

冷冻紫红色包裹

如需冻结名为 my-package 的 Fuchsia 软件包，请执行以下操作：

将软件包从 fuchsia_package 更改为 ctf_fuchsia_package。
将{PACKAGE_NAME}_archive目标添加到 //sdk/ctf/tests:tests.

示例：

# Old src/my-package/BUILD.gn
import("//build/components/fuchsia_package.gni")

fuchsia_package("my-package") {
  # ...
}

将您的文件更改为：

# New src/my-package/BUILD.gn
import("//sdk/ctf/build/ctf.gni")

ctf_fuchsia_package("my-package") {
  # ...
}

并更新 //sdk/ctf/tests/BUILD.gn：

group("tests") {
  deps = [
    # ...
    "//src/my-package:my-package_archive",
  ]
}

您还可以在本地 BUILD.gn 中创建 group("ctf_tests")，并在 //sdk/ctf/tests/BUILD.gn 中引用它。

这会导致您的软件包被编译并存储在 ctf-artifacts 当下一个 Fuchsia 里程碑发布时。完成此步骤后，您需要必须包含有关如何加载软件包的说明（请参阅下一部分）。

加载 Fuchsia 软件包

要加载冻结的 Fuchsia 软件包，您需要更新 generate_ctf_tests.gni 添加文件包加载说明。

您需要在 generate_ctf_tests.gni 中定义一个新模板名为 generate_my-package 的文件，并且此模板必须展开为 Fuchsia 测试软件包。

该模板将接收一个名为 test_info 的参数包含已下载软件包的标签，即 test_info.target_label。

例如：

template("generate_my-package") {
  forward_variables_from(invoker, [ "test_info" ])
  fuchsia_package_with_test(target_name) {
    test_component = "//src/my-package:my-package-test-root",
    test_component_name = "test-root.cm"
    subpackages = [
      test_info.target_label, # prebuilt version of the test suite.
      # other packages needed to implement the test, such as a RealmFactory.
    ]
  }
}

冻结主机测试

如需冻结主机测试，请执行以下操作：

将构建规则从 host_test 更改为 ctf_host_test。
包含该定位条件 //sdk/ctf/tests:tests.

示例：

# Old src/my-host-test/BUILD.gn
import("//build/testing/host_test.gni")

host_test("my-host-test") {
  # ...
}

将您的文件更改为：

# New src/my-host-test/BUILD.gn
import("//sdk/ctf/build/ctf.gni")

ctf_host_test("my-host-test") {
  # ...
}

并更新 //sdk/ctf/tests/BUILD.gn：

group("tests") {
  deps = [
    # ...
    "//src/my-host-test:my-host-test",
  ]
}

您还可以在本地 BUILD.gn 中创建 group("ctf_tests")，并在 //sdk/ctf/tests/BUILD.gn 中引用它。

这将导致您的主机测试及其依赖项被捆绑当下一个 Fuchsia 里程碑发布后，在 ctf-artifacts 中。完成此步骤后，您的测试将自动在 CTF 中运行使用传递给 ctf_host_test 的任何参数。

基本概念

CTF 由两种机制组成：

构建规则以冻结工件并将其上传到 CIPD。
构建规则，解冻该工件进行测试。

在 fuchsia.git 的顶端执行冻结和加载过程。用于通过 //sdk/ctf 构建目标进行本地测试的代码库。包括 fx set 参数中的 --with-test //sdk/ctf 会产生以下结果：构建输出：

$FUCHSIA_DIR/out/default/cts/host_test_manifest.json
$FUCHSIA_DIR/out/default/cts/package_archives.json
$FUCHSIA_DIR/out/default/cts/*.far       # Packages referenced in manifest
$FUCHSIA_DIR/out/default/cts/host_x64/*  # Host tests referenced in manifest

这会生成原始测试和这些测试的解冻版本：

$ fx test --dry
...
  fuchsia-pkg://fuchsia.com/fuchsia-diagnostics-tests-latest#meta/fuchsia-diagnostics-tests-root.cm
  fuchsia-pkg://fuchsia.com/fuchsia-driver-test_tests-package#meta/test-root.cm
...
  fuchsia-pkg://fuchsia.com/fuchsia-diagnostics-tests_ctf_in_development#meta/fuchsia-diagnostics-tests-root.cm
  fuchsia-pkg://fuchsia.com/fuchsia-driver-test_tests_ctf_in_development#meta/test-root.cm

generate_ctf_tests.gni 中定义的规则如下：负责解冻 package_archives.json 中引用的软件包具体方法是将它们转换为常规的 Fuchsia 测试软件包。由于这些从 CTF build 解冻后，它们都有 ctf_in_development 后缀。所有这些测试使用 fx test 运行。

每个 Fuchsia 里程碑版本（例如 F16 和 F17）都是与 Git 中的版本分支相关联（例如， refs/heads/releases/F16。上述过程版本分支的每项更改，都会产生一个新的 ctf 目录，其中包含清单中引用的软件包和托管测试。而在版本分支上，生成的目录会经过压缩并已上传到 CIPD，并从中下载 jiri run-hooks。您可以在在prebuilt/ctf/f*结账，fuchsia.git，其中有一个目录。数据来源哪些里程碑的预构建文件下载时间 version_history.json，其中列出了 supported 要测试的 API 级别。

在 //sdk/ctf/release:tests 中定义的构建目标会迭代下载的预构建文件，并将要解除每条规则的 generate_ctf_tests.gni 条规则下载软件包的方式与开发中的软件包相同融化了您可以在 fx set 参数中使用 --with-test //sdk/ctf/release:tests 添加这些变量。

这会将每个受支持级别的新测试添加到您的 build 中：

$ fx test --dry
...
  fuchsia-pkg://fuchsia.com/fuchsia-diagnostics-tests_ctf18#meta/fuchsia-diagnostics-tests-root.cm
  fuchsia-pkg://fuchsia.com/fuchsia-driver-test_tests_ctf18#meta/test-root.cm
...
  fuchsia-pkg://fuchsia.com/fuchsia-diagnostics-tests_ctf19#meta/fuchsia-diagnostics-tests-root.cm
  fuchsia-pkg://fuchsia.com/fuchsia-driver-test_tests_ctf19#meta/test-root.cm

每个解冻测试都有一个后缀，用于指示版本分支，其中生成的冻结软件包（例如 F18 和 F19 的 ctf18、ctf19））。所有这些测试都可以使用 fx test 运行。

失败问题排查

当存在不兼容的情况时，CTF 测试会失败冷冻文件包和 fuchsia.git，这可能会导致 core.x64-debug-ctf 构建器在 CL 提交过程中失败。请参阅问题排查指南，获取详细说明介绍了如何处理失败情形，以取消阻止 CL 提交流程。