對 CTF 做出測試

本指南說明如何新增及移除 CTF 測試。

如何將測試新增至 CTF

開始前，請先詳閱 CTF 測試規定。最值得注意的規定是，測試必須使用測試領域工廠，才能按照本指南操作。

如果測試位於 //sdk/ctf/tests:tests 的群組中，就會納入 CTF。將測試新增至這個群組前，必須先重新編寫建構規則，使用 CTF 版本。很抱歉，這是必要步驟，但很快就會取消。

如要將測試新增至這個群組，請在包含測試 fuchsia_test_component 目標的 BUILD.gn 檔案中，執行下列每個步驟。

1. 匯入 CTF 建構規則

import("//sdk/ctf/build/ctf.gni")

2. 使用 CTF GN 範本

將測試的 fuchsia_package 宣告替換為 ctf_fuchsia_package：

使用前

fuchsia_package("fuchsia-example-tests") {
  testonly = true
  package_name = "fuchsia-example-tests"
  deps = [ ":fuchsia-example-test-component" ]
}

使用後

ctf_fuchsia_package("fuchsia-example-tests") {
  testonly = true
  package_name = "fuchsia-example-tests"
  deps = [ ":fuchsia-example-test-component" ]
}

3. 將測試版封存檔新增至建構圖

ctf_fuchsia_package 會產生 ${target_name}_archive 目標，用於產生測試的 FAR 封存檔。這個封存檔就是 CTF 中發布的內容。如果 BUILD.gn 檔案中沒有 group("tests") 目標，請新增一個，然後將封存檔新增為依附元件：

group("tests") {
  testonly = true
  deps = [
    ":fuchsia-example-tests_archive",
    ...
  ]
}

您已成功將 group("tests")新增至 BUILD.gn 檔案。現在，您已準備好將該群組新增至 //sdk/ctf/tests:tests。

4. 新增 GN 範本，建構預先建構的 CTF 測試

如要教導 CTF 如何將測試的預先建構套件建構為可執行的目標，請建立 GN 範本，產生與 fuchsia_test_package 相同的套件，用於執行最新版本的測試。舉例來說，如果測試根元件和測試套件如下所示：

fuchsia_test_component("fuchsia-example-test-root") {
  testonly = true
  manifest = "meta/fuchsia-example-test-root.cml"
  test_type = "ctf"
}

fuchsia_test_package("fuchsia-example-tests-latest") {
  test_components = [ ":fuchsia-example-test-root" ]
  subpackages = [
    ":fuchsia-example-tests", # latest version of the test suite.
    ":fuchsia-example-test-realm-factory",
  ]
  deps = [ ":fuchsia-example-test-helper" ]
}

然後將這個範本新增至 //sdk/ctf/build/generate_ctf_tests.gni

template("generate_fuchsia-example-tests") {
  forward_variables_from(invoker, [ "test_info" ])
  fuchsia_package_with_test(target_name) {
    test_component = "//path/to/test:fuchsia-example-test-root",
    test_component_name = "test-root.cm"
    subpackages = [
      test_info.target_label, # prebuilt version of the test suite.
      "//path/to/test:fuchsia-example-test-realm_factory"
    ]
    deps = [ "//path/to/test:fuchsia-example-test-helper" ]
  }
}
  • 如要讓 CTF 將這個範本與預先建構的測試套件相符，這個範本必須命名為 generate_{package_name}，且 package_name 必須與測試的原始 ctf_fuchsia_package 名稱相符。
  • 這個範本會使用 test_info.target_label，而不是 :fuchsia-example-tests，因為前者指向 CIPD 的預先建構測試版本，後者則指向從來源建構的最新版本。

5. 測試變更

如要確認這些步驟是否正確完成，請執行下列指令：

fx set core.x64 --with //sdk/ctf:ctf_artifacts
fx build

建構作業應會顯示錯誤提示，要求執行指令來更新 //sdk/ctf/goldens/package_archives.json。執行該指令，然後再次執行 fx build。

如果缺少上一個步驟中定義的 GN 範本，或無法將測試的預先建構版本與 GN 範本相符，建構作業就會在這個階段列印錯誤。如果一切順利，即可使用下列指令執行測試：

fx test fuchsia-example-test_ctf<N>

由於這是目前建構版本中的預建測試版本，而非先前 CTF 發布版本中的某個版本，因此 N 是 Fuchsia 平台目前開發中的 API 級別。

6. 提交變更

將變更送審。提交後，系統會在下一個里程碑分支版本發布時，自動將測試納入下一個 CTF 版本。如需進一步審查，請傳送電子郵件至 fuchsia-ctf-team@google.com。

如何從 CTF 移除測試

如要從日後的 CTF 版本中移除測試，請按照下列步驟操作：

  1. 從建構圖中移除測試封存檔。
  2. 刪除測試的 gn 範本。
  3. 從測試的建構規則中移除 ctf 範本。

將這些變更提交至主要分支版本。隨著時間推移，每個版本對應的 API 級別都會停止支援，且最後一個版本的測試也會停止在 CQ 中執行。

如果必須立即從 CQ 移除測試和所有預先建構的版本，請按照 Fuchsia 的變更控制程序，額外挑選 CL，從各個對應的發布分支版本移除測試。舉例來說，如要從 API 級別 20 的 CTF 版本中移除測試，就必須將 CL 挑選到 releases/f20 分支。

測試規定

所有測試都必須符合這些規定，才能加入 CTF。

CTF 測試必須使用測試領域工廠模式

測試領域工廠模式可讓建構作業在 CTF 中為測試套件元件設定版本，而不必為受測元件設定版本。請先閱讀測試領域工廠指南，並視需要重構測試，再按照本指南操作。

CTF 測試只能依附於合作夥伴面向的 ABI

CTF 測試只能在執行階段依附於合作夥伴 SDK 類別中的軟體，因為測試會強制依附元件保持穩定。預先提交檢查不會強制執行這項操作。通常測試作者只需要確認測試套件元件使用的 FIDL 通訊協定，是否都位於 partner SDK 類別中。

CTF 測試必須以 C、C++ 或 Rust 編寫

撰寫本文時，CTF 僅支援這些語言。