测试元数据

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 将 subcategory: "Archivist" 设置为将所有与 Archivist 相关的测试归为一组。

  • 为跨团队或跨组件问题设置标记。

    例如，src/diagnostics/lib 和 src/lib/diagnostics 都会设置 "lib" 标记。然后，我们可以对整个树中所有“库”的覆盖率进行分组。

示例

假设有以下来源布局：

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"],
  },
}