CTF 使用手冊

本使用手冊將全面介紹 Fuchsia (CTF) 的相容性測試，這套機制可讓您凍結版本分支版本的構件，以及將其載入 main 分支版本中以進行測試。

CTF 最常見的用途是凍結分支版本測試，然後針對 CI/CQ 中 main 分支版本上的元件執行測試。這樣就能防止回溯不相容的變更，以免破壞預先建構的用戶端。

如要進一步瞭解整體 CTF，請參閱總覽和動機說明文件。

基本用法

本節說明如何使用 CTF 及處理常見情境的方式。

凍結 Fuchsia 套組

如要凍結名為 my-package 的 Fuchsia 套件，請按照下列步驟操作：

  1. 將套件從 fuchsia_package 變更為 ctf_fuchsia_package。
  2. 在 //sdk/ctf/tests:tests 中加入 {PACKAGE_NAME}_archive 目標。

例子：

# 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 中參照此項目。

這會導致在下一個 Fuchsia 里程碑發布時，編譯及儲存在 ctf-artifacts 中。完成這個步驟後，請務必提供載入套件的操作說明 (請參閱下一節)。

正在載入 Fuchsia 套件

如要載入凍結的 Fuchsia 套件，您必須更新 generate_ctf_tests.gni，加入載入套件的操作說明。

您需要在名為 generate_my-package 的 generate_ctf_tests.gni 檔案中定義新範本，且這個範本必須展開為 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.
    ]
  }
}

凍結主機測試

如要凍結主機測試，請按照下列步驟操作：

  1. 將建構規則從 host_test 變更為 ctf_host_test。
  2. 請在 //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_host_test 的任何引數，在 CTF 自動執行測試。

基本概念

CTF 包含兩種機制：

  1. 建構規則來凍結構件，並將其上傳至 CIPD。
  2. 「建構規則」，隱藏構件並轉換為測試。

根據 //sdk/ctf 建構目標，在本機測試的 fuchsia.git 存放區中，會執行凍結和載入程序。在 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 中定義的規則必須轉換為一般的 Fuchsia 測試套件，才能對 package_archives.json 中參照的套件做出負責。由於這些套件是在樹狀結構的基礎上遭到 CTF 建構作業停用，因此全都加上 ctf_in_development 後置字串。這些測試均可使用 fx test 執行。

每個 Fuchsia 里程碑版本 (例如 F16 和 F17) 都與 Git 中的版本分支版本相關聯 (例如 refs/heads/releases/F16)。系統會對每個發布分支版本的變更執行上述程序，產生新的 ctf 目錄，其中包含資訊清單中參照的套件和主機測試。不過，在發布分支版本中，產生的目錄會經過壓縮並上傳至 CIPD，並以 jiri run-hooks 的形式下載該目錄。您可以在 prebuilt/ctf/f* 的 fuchsia.git 結帳頁面找到這些下載的預先建構項目，每個 Fuchsia 里程碑版本都有一個目錄。要下載預建里程碑的可靠資料來源是 version_history.json，其中會列出要測試的 supported API 級別。

//sdk/ctf/release:tests 定義的建構目標會疊代下載的預先建構項目，並套用 generate_ctf_tests.gni 規則處理每個下載的套件，方式與開發中的套件相同。您可以在 fx set 引數中使用 --with-test //sdk/ctf/release:tests 加入這些引數。

這項操作會針對建構作業中的每個支援級別新增測試：

$ 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

每個通過的測試都有一個後置字串，指出凍結套件的來源發布分支版本 (例如 ctf18、ctf19 代表 F18 和 F19)。這些測試均可使用 fx test 執行。

排解失敗問題

如果凍結套件與 fuchsia.git 最先產生的套件不相容，CTF 測試就會執行失敗，導致 core.x64-debug-ctf 建構工具在 CL 提交期間失敗。如需處理失敗情況以解除封鎖 CL 提交內容的詳細操作說明，請參閱專屬疑難排解指南。