測試中繼資料

Fuchsia 會使用 TESTING.json5 檔案，為每個目錄的測試提供額外中繼資料。這項中繼資料可用於在資訊主頁和報表工具中，整理及顯示測試涵蓋範圍。

目的

TESTING.json5 的主要用途是將目錄 (以及其中的測試) 與特定類別建立關聯，並視需要與其他中繼資料建立關聯。

主要用途包括：

  • 在作業系統的不同領域中，以視覺化方式呈現測試涵蓋範圍。
  • 找出缺少測試或有未分類測試的區域。

位置

TESTING.json5 檔案應放置在來源樹狀結構中元件、子系統或主要目錄的根目錄。例如：

  • src/diagnostics/TESTING.json5

除非樹狀結構中較深處有其他 TESTING.json5 檔案覆寫，否則放在目錄中的檔案會套用至該目錄和所有子目錄。

格式

這個檔案是 JSON5 文件，內含具有 coverage 欄位的單一物件。coverage 欄位包含零或多個下列欄位：

  • category：代表類別的選用字串。
  • subcategory：選用字串，提供更具體的子類別。
  • tags：代表標記的選用字串清單。

以下是結構定義：

{
  coverage: {
    category: "Category Name",
    subcategory: "Subcategory Name",
    tags: ["tag1", "tag2"],
  },
}

覆寫行為

TESTING.json5 檔案會套用至所有子目錄，但個別欄位可以覆寫，方法如下：

  • coverage.category 和 coverage.subcategory 欄位互斥。如果子目錄已設定其中一個欄位，系統會覆寫最接近的 TESTING.json5 父項中相符的欄位。
  • coverage.tags 欄位為附加欄位。如果子目錄有 coverage.tags 欄位，系統會將標記與每個祖系 TESTING.json5 檔案中的標記合併。

查看類別

您可以使用 fx test-category 工具，查看樹狀結構中任何目錄的計算類別。使用這項工具驗證計算出的類別是否合理，並找出未分類的目錄。

將目錄傳遞至工具，即可查看最終計算出的類別：

fx test-category src/diagnostics/archivist

這會顯示輸出內容：

src/diagnostics/archivist:
  category: "Diagnostics"
  subcategory: "Archivist"
  tags: []

傳遞 --stats 旗標，即可改為顯示指定子目錄或整個樹狀結構的匯總統計資料：

fx test-category src/diagnostics --stats

這會顯示輸出內容：

Categories and Subcategories:
  Diagnostics: 214
    Archivist: 45
    Test Only: 38
    None: 32
    Libraries: 26
    Detect: 18
    Utilities: 16
    Sampler: 16
    Persistence: 9
    Triage: 9
    Tools: 5

Tags:
  lib: 26

傳遞 --web 旗標，啟動簡易網頁，即可互動式瀏覽及查看樹狀結構的類別：

fx test-category --web

這會顯示輸出內容：

View categories at http://localhost:6240?files=metadata.json
Not seeing the categories you expect? Run `touch BUILD.gn` and then `fx build`

Press enter to stop the server.

類別樣式指南

TESTING.json5 的格式刻意寬鬆，以便隨著時間逐步調整類別，而且暫時選錯類別的成本很低。

您只需要遵守幾項硬性規定，系統會自動強制執行：

  • 每個目錄都有類別。

    頂層 //TESTING.json5 檔案會滿足這項條件。

  • 如果目錄的類別為「未分類」，則可能沒有子類別。

  • 每個 TESTING.json5 檔案都必須以 fx format-code 格式設定。

建議的類別版面配置

請參考下列建議：

  • 為子系統或元件的頂層目錄提供類別， 但不必為每個子目錄提供類別。

    舉例來說，src/diagnostics 可以設定 category: "Diagnostics"，而子目錄 src/diagnostics/lib 和 src/diagnostics/archivist 則會直接沿用該類別。

  • 類別通常會對應至團隊名稱，但並非必要。一般來說，這些名稱應與目錄命名相符。

    舉例來說，如果目錄所屬團隊為「診斷」，則類別為「診斷」。

  • 在分類目錄的子目錄中設定子類別。這些名稱應與子目錄的用途相關。

    舉例來說，src/diagnostics/archivist 會將所有與 Archivist 相關的測試分組。subcategory: "Archivist"

  • 為跨團隊或跨元件的問題設定標記。

    舉例來說，src/diagnostics/lib 和 src/lib/diagnostics 都會設定 "lib" 標記。然後，我們可以將樹狀結構中所有「libs」的涵蓋範圍分組。

範例

假設來源配置如下：

src/my_team/
src/my_team/component1/
src/my_team/component2/
src/my_team/lib/
src/my_team/lib/component1_client
src/lib/my_team/server_library

請考慮建立下列檔案：

// src/my_team/TESTING.json5
{
  coverage: {
    category: "My Team",
  },
}

// src/my_team/component1/TESTING.json5
{
  coverage: {
    subcategory: "Component1",
  },
}

// src/my_team/component2/TESTING.json5
{
  coverage: {
    subcategory: "Component2",
  },
}

// src/my_team/lib/TESTING.json5
{
  coverage: {
    tags: ["lib"],
  },
}

// src/lib/my_team/TESTING.json5
{
  coverage: {
    category: "My Team",
    tags: ["lib"],
  },
}