Fuchsia test.json 檔案格式

Fuchsia 的建構系統會針對建構輸出目錄的 tests.json 檔案 (例如 $FUCHSIA_DIR/out/default/tests.json)，將建構作業中包含的所有測試的結構化資訊匯出。

Fuchsia 的持續整合基礎架構使用 tests.json 決定要執行哪些測試，fx test 則用來判斷哪些測試可在本機執行。tests.json 及其結構定義是平台建構與測試的實作詳細資料，並不隸屬於 SDK。

本文件會說明檔案內容以及檔案產生方式。

產生 test.json

tests.json 檔案是由來源樹狀結構根目錄中的 「tests」API 模組產生。

tests.json 項目的欄位會透過 GN 中繼資料機制收集。系統會使用 test_spec GN 範本從 GN 檔案註冊 tests.json 項目。

tests.json 是由 fx set 自動產生。tests.json 格式受限於使用 GN 相對有限的中繼資料機制，可從 GN 立即產生的內容限制。為了突破這些限制，Fuchsia 版本也會產生名為 test-list.json 的檔案，該檔案是由後續處理 tests.json 所產生，如下所述。

test.json 消費者

各種工具和指令碼會擷取 tests.json 檔案，因為該檔案是特定 Fuchsia 版本可用測試的標準清單。這個部分對這個廣告格式的知名消費者進行問卷調查。

test_list_tool

test_list_tool 會處理 tests.json。使用標準測試清單時，會使用內含的套件資訊清單資訊載入建構套件，並在每項測試中加註有關執行方式和其他分類標記的資訊。例如，它可以判斷測試元件是否以小米方式執行，並使用 "hermetic": true 標記測試。

test_list_tool 會將此資訊輸出至 tests.json 旁邊的 test-list.json 檔案，並在建構所有套件後，做為最後一個建構步驟之一。這個函式會使用與 tests.json 相同的專屬 name 鍵，以便比對項目。

Fx 搜尋測試

fx search-tests 指令碼可針對測試名稱提供模糊比對，協助開發人員找出可執行的測試。除了透過來源樹狀結構搜尋未納入的測試外，也會使用 tests.json 中的值做為模糊比對的鍵。

外匯測試

fx test 指令是提供給開發人員的進入點，用於測試 Fuchsia 來源樹狀結構中的執行作業。然後使用 tests.json 決定標準測試組合，然後在 test-list.json 和 test_components.json 中找到相關資料，判斷如何執行測試。

植物學家 / 測試困難

基礎架構中的 testsharder 依附於 tests.json，根據環境維度對測試項目進行資料分割。這項程序的輸出內容是包含來自 tests.json 欄位的另一個檔案，接著系統會將其傳遞至執行測試的機器人上的植物學。

test.json 結構

tests.json 是由單一陣列組成的 JSON 檔案。陣列的每個元素都會對應至建構中的單一測試目標項目。

測試目標項目有兩個頂層欄位 (environments 和 test)，分別對應至測試環境和測試資訊。

欄位

環境欄位

environments 欄位是測試環境項目的陣列。每個測試環境項目都會指定可執行測試的單一環境，而這個欄位會供測試者在裝置設定之間進行資料分割測試。

每個測試環境項目都有一個 dimensions 欄位，以及任意數量的任意維度。但最常見的兩個欄位組合如下：

  • device_type：指定測試所需的裝置類型。例如：

    "environments": [
    {
        "dimensions": {
            "device_type": "QEMU"
        }
    }
]

    這代表可透過 QEMU 裝置設定執行的測試。注意：這並不代表測試在「任何」QEMU 裝置上執行，而是代表測試會根據 botanist 使用的設定在 QEMU 執行個體上執行。

  • cpu 和 os：指定主機測試所需的 CPU 架構和作業系統。例如：

    "environments": [
    {
        "dimensions": {
            "cpu": "x64",
            "os": "Linux"
        }
    }
]

    這會指定可在 x64 Linux 系統上執行的測試。

  • tags - 指定資料分割的其他屬性。例如：

    "environments": [
  {
    "tags": [ "e2e-isolated" ]
  }
]

    這會指定含有「e2e-isolated」標記的測試。

    除非建構設定明確選擇以該標記執行測試，否則使用環境標記的測試將不會在持續整合建構作業中執行，在這種情況下，「只會」以該標記進行測試。

測試欄位

test 欄位提供有關如何分類、執行及設定測試的資訊。fx test 和 botanist 等測試執行工具會使用這項資料，決定用於執行測試的正確二進位檔和指令列。其中包含的資訊對於其他整合工具相當實用，例如可以在測試叫用之間重新建立測試目標。

測試通常分為兩種類型：主機和裝置。主機測試指的是執行測試的主機系統上的二進位檔路徑。裝置測試會參照使用 Test Manager 在目標系統上執行的元件網址。

有些主機測試需要使用 Fuchsia 裝置，有些則不需要。端對端測試 (E2E) 的 os 不是「fuchsia」，但在其 environments 中仍會指定 device_type。

test 物件包含下列欄位，並依據測試類型分割：

所有測試

  • name - 測試名稱。這個值在 tests.json 中不會重複。通常包含裝置測試的測試元件網址，以及相對於主機測試輸出目錄的測試二進位檔路徑。
  • cpu：執行這項測試的 CPU 架構。使用 environments 項目進行主機測試，但此資訊是裝置測試的唯一來源。
  • os：執行這項測試的作業系統。使用 environments 項目進行主機測試，但此資訊是裝置測試的唯一來源。botanist 會使用這個欄位判斷是否應在主機上以子程序執行測試，或透過 SSH 至目標裝置執行測試。
  • label：產生此測試項目的 GN 標籤。用於知道從 fx test 執行測試時要重新建構哪些目標，但僅適用於此標籤實際輸出實際測試二進位檔的主機測試。其他類型的測試使用不同的標籤欄位，例如 package_label。

僅限主機測試

  • path：相對於輸出目錄的測試二進位檔路徑。僅供主機測試顯示。
  • runtime_deps：JSON 檔案的路徑 (相對於輸出目錄)，其中包含檔案路徑清單 (相對於輸出目錄)，該檔案應存放在已知的主機測試位置，以便在執行階段使用。檔案格式是檔案路徑字串的 JSON 陣列。

僅限裝置測試

  • has_generated_manifest - 如果這個測試元件的資訊清單是由 GN 規則產生，則為「true」；如果是主機測試，則省略「false」。用於使用自訂資訊清單的測試分類和追蹤測試。
  • build_rule - 由版本產生，用於進一步測試分類。舉例來說，知道測試是由 fuchsia_unittest_package 或 fuchsia_test_package 規則建立，就十分有用。
  • log_settings - 字典，可能包含下列欄位：
    • max_severity：此欄位會覆寫測試的預設記錄嚴重性上限。根據預設，發送 ERROR 記錄的測試會失敗，但這個欄位會指示測試執行工具在有不同記錄層級導致失敗的模式下執行。
    • min_severity：用於指示測試元件在這個層級 (而非預設值) 發出記錄。根據預設，測試會選擇自己的最低記錄嚴重性。
  • package_label：產生這項測試套件的 GN 標籤。僅適用於裝置測試。由 fx test 用於重新建構含有測試的套件，然後再執行測試。
  • component_label：產生此測試測試元件的 GN 標籤。如果在 fx search-tests 中找不到相符的測試，除了所有其他標籤欄位以外，這是用於模糊比對的測試名稱。僅適用於裝置測試。
  • package_manifests：建構測試套件時所用每個套件資訊清單的路徑清單 (相對於輸出目錄)。在 fx test 中建構測試後，用於判斷要重新發布的套件。僅適用於裝置測試。
  • package_url：與這項測試對應的測試元件網址。這是測試管理員為了裝置測試而要求執行的網址。
  • parallel：為預設測試執行元件平行處理而覆寫 (以整數表示)。通常用於指示測試執行工具，指示 ffx test 不要針對含有 Crosstalk 的測試同時執行測試案例。 將這個值設為 1 會停用平行測試案例執行作業，數字 > 1 則會在個別測試執行元件支援的情況下，強制執行平行測試案例。

範例

主機測試

[
  {
    "environments": [
      {
        // This test runs on the infra shard for Linux x64.
        "dimensions": {
          "cpu": "x64",
          "os": "Linux"
        }
      }
    ],
    "test": {
      "cpu": "x64",
      "label": "//src/performance/trace2json:trace2json_tests(//build/toolchain:host_x64)",
      "name": "host_x64/trace2json_tests",
      "os": "linux",
      // This is the path to execute the test both locally and in infra.
      "path": "host_x64/trace2json_tests",
      // The deps listed in this file must be placed in a known
      // location for the test.
      "runtime_deps": "host_x64/gen/src/performance/trace2json/trace2json_tests.deps.json"
    }
  }
]

裝置測試

[
  {
    "environments": [
      // This test runs on the AEMU shard in infra.
      {
        "dimensions": {
          "device_type": "AEMU"
        }
      }
    ],
    "test": {
      // This test was created using fuchsia_unittest_package
      "build_rule": "fuchsia_unittest_package",
      "component_label": "//src/diagnostics/lib/sampler-config:sampler-config-tests_component(//build/toolchain/fuchsia:x64)",
      "cpu": "x64",
      // This test specified its own manifest.
      "has_generated_manifest": false,
      "label": "//src/diagnostics/lib/sampler-config:sampler-config-tests_test_sampler-config-tests_component(//build/toolchain/fuchsia:x64)",
      "log_settings": {
        // Any ERROR or FATAL logs will force this test to fail.
        "max_severity": "WARN"
      },
      "name": "fuchsia-pkg://fuchsia.com/sampler-config-tests#meta/sampler-config-tests.cm",
      "os": "fuchsia",
      "package_label": "//src/diagnostics/lib/sampler-config:sampler-config-tests(//build/toolchain/fuchsia:x64)",
      // These manifests can be used for deep inspection of the
      // contents of this test.
      "package_manifests": [
        "obj/src/diagnostics/lib/sampler-config/sampler-config-tests/package_manifest.json"
      ],
      "package_url": "fuchsia-pkg://fuchsia.com/sampler-config-tests#meta/sampler-config-tests.cm"
    }
  }
]