此页面由 Cloud Translation API 翻译。

Fuchsia tests.json 文件格式

Fuchsia 的构建系统会将构建中包含的所有测试的结构化信息导出到构建输出目录中的 tests.json 文件（例如 $FUCHSIA_DIR/out/default/tests.json）。

Fuchsia 的持续集成基础架构使用 tests.json 来确定要运行哪些测试，而 fx test 使用它来确定可以在本地运行哪些测试。tests.json 及其架构是平台构建和测试的实现细节，不属于 SDK 的一部分。

本文档介绍了该文件的内容以及该文件的生成方式。

生成 tests.json

tests.json 文件会在 regenerator.py 中的 gn-gen 之后立即生成。

系统使用 GN 元数据机制收集 tests.json 条目的字段。tests.json 条目是使用 test_spec GN 模板从 GN 文件注册的。

tests.json 由 fx set 自动生成。tests.json 格式受限于使用 GN 的相对有限的元数据机制从 GN 中轻松生成的内容。为了解决这些限制，Fuchsia build 还会生成一个名为 test-list.json 的文件，该文件由 tests.json 的后处理生成，如下所述。

tests.json 使用方

各种工具和脚本都会提取 tests.json 文件，因为它是给定 Fuchsia build 可用测试的规范列表。本部分将介绍该格式的最显著使用情形。

test_list_tool

test_list_tool 会处理 tests.json。它使用规范测试列表中的包含的软件包清单信息加载 build 软件包，并为每个测试添加注解，其中包含有关其应如何执行的信息以及用于进一步分类的标记。例如，它可以确定测试组件是否以密封方式运行，并使用 "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

在 Infra 中，testsharder 依赖于 tests.json，以便根据环境维度分片测试条目。该进程的输出是另一个文件，其中包含从 tests.json 派生的字段，然后该文件会传递到运行测试的聊天机器人上的 botanist。

tests.json 结构

tests.json 是一个由单个数组组成的 JSON 文件。数组中的每个元素都对应于 build 中的单个测试目标条目。

测试目标条目有两个顶级字段，environments 和 test，分别对应于“测试环境”和“测试信息”。

字段

environments 字段

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”的测试。

带有环境标记的测试不会在持续集成 build 中运行，除非 build 配置明确选择运行带有该标记的测试，在这种情况下，仅运行带有该标记的测试。

测试字段

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 文件包含应放置在主机测试所知位置以便在运行时使用的文件的文件路径列表（相对于输出目录）。该文件的格式为文件路径字符串的 JSON 数组。

仅限设备测试

has_generated_manifest - 如果这是由 GN 规则生成清单的测试组件，则为 true；如果测试是宿主测试，则省略；否则为 false。用于使用自定义清单对测试进行分类和跟踪。
build_rule - 由 build 生成，以便进一步对测试进行分类。例如，了解测试是通过 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"
    }
  }
]