Fuchsia 的构建系统会将关于 build 中包含的所有测试的结构化信息导出到 build 输出目录下的 tests.json
文件(例如 $FUCHSIA_DIR/out/default/tests.json
)。
Fuchsia 的持续集成基础架构使用 tests.json
来确定要运行哪些测试,fx test
则使用它来确定哪些测试可以在本地运行。tests.json
及其架构是平台构建和测试的实现细节,不是 SDK 的一部分。
本文档介绍了该文件的内容以及生成方式。
生成 Testing.json
tests.json
文件由源代码树根目录下的“tests”API 模块生成。
tests.json
条目的字段是使用 GN 元数据机制收集的。tests.json
条目是使用 test_spec
GN 模板从 GN 文件注册的。
tests.json
由 fx set
自动生成。tests.json
格式受 GN 使用 GN 相对有限的元数据机制轻松生成的内容的限制。为了克服这些限制,Fuchsia build 还会生成名为 test-list.json
的文件,该文件由后处理 tests.json
生成(如下所述)。
Testing.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
脚本可对测试名称进行模糊匹配,以帮助开发者查找可以运行哪些测试。除了通过源代码树搜索未包含的测试之外,它还会使用 tests.json
中的值作为键以进行模糊匹配。
FX 测试
fx test
命令是面向开发者的入口点,用于测试 Fuchsia 源代码树中的执行情况。它使用 tests.json
来确定一组规范测试,然后在 test-list.json
和 test_components.json
中查找关联的数据以确定应如何执行测试。
植物学家 / 测试分片员
在基础架构中,testfragmenter 依赖于 tests.json
来根据环境维度对测试条目进行分片。该进程的输出是另一个文件,其中包含派生自 tests.json
的字段,该字段随后会传递给运行测试的机器人上的植物学家。
Testing.json 结构
tests.json
是由单个数组组成的 JSON 文件。数组的每个元素都对应于 build 中的单个测试目标条目。
测试目标条目有两个顶级字段: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”标记的测试。
带有环境标记的测试将不会在持续集成 build 中运行,除非 build 配置明确选择运行带有该标记的测试,在这种情况下,将仅运行带有该标记的测试。
测试字段
test
字段提供有关如何对测试进行分类、运行和配置的信息。fx test
和 botanist
等测试执行程序会使用这些数据来确定执行测试的正确二进制文件和命令行。它还包含对其他工具集成有用的信息,例如在测试调用之间重新构建测试目标。
通常有两种测试类型:主机测试和测试类型。主机测试是指主机系统上为了执行测试而运行的二进制文件路径。设备测试是指使用测试管理器在目标系统上运行的组件网址。
有些主机测试需要使用 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 规则生成的测试组件,则为 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
- 与此测试对应的测试组件网址。 这是请求测试管理器为设备测试执行的网址。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"
}
}
]