本頁面由 Cloud Translation API 翻譯而成。

Fuchsia test.json 檔案格式

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

Fuchsia 的持續整合基礎架構會使用 tests.json 判斷要執行哪些測試，而 fx test 會使用 tests.json 判斷哪些測試可在本機執行。tests.json 及其結構定義是平台建構和測試的實作詳細資料，並非 SDK 的一部分。

本文件說明檔案內容和產生方式。

產生 tests.json

tests.json 檔案會在 regenerator.py 中的 gn-gen 之後立即產生。

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

tests.json 是由 fx set 自動產生。tests.json 格式受到 GN 中相對有限的中繼資料機制限制，無法輕易產生。為了克服這些限制，Fuchsia 版本也會產生名為 test-list.json 的檔案，這是透過後置處理 tests.json 產生的，如以下所述。

tests.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 search-tests

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

fx test

fx test 指令是開發人員面向的進入點，可用於測試 Fuchsia 來源樹狀結構中的執行作業。它會使用 tests.json 判斷常規測試集，然後在 test-list.json 和 test_components.json 中找出相關聯的資料，以決定如何執行測試。

botanist / testsharder

在基礎架構中，testsharder 會依賴 tests.json，根據環境維度分割測試項目。該程序的輸出內容是另一個檔案，其中包含從 tests.json 衍生的欄位，然後會在測試執行的機器人上傳遞至 botanist。

tests.json 結構

tests.json 是 JSON 檔案，其中包含單一陣列。陣列的每個元素都對應至建構中單一測試目標項目。

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

欄位

環境欄位

environments 欄位是測試環境項目的陣列。每個「測試環境」項目都會指定測試可能執行的單一環境，而這個欄位會由 testsharder 用於在裝置設定之間分割測試。

每個測試環境項目都包含單一欄位 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 不是「紫紅色」，但仍在其 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 規則產生的資訊清單的測試元件，則為「是」；如果測試是主機測試，則省略；否則為「否」。用於使用自訂資訊清單進行測試分類和追蹤。
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：與此測試相對應的測試元件網址。這是 Test Manager 要求執行裝置測試的網址。
parallel - 覆寫預設的測試執行元件並行處理作業 (以整數表示)。通常用於指示測試執行程式，告知 ffx test 不要針對有交談的測試並行執行測試案例。將這個值設為 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"
    }
  }
]