测试执行环境的详尽规范。
背景
Bazel BUILD 语言包含一些规则，可用于用多种语言定义自动化测试程序。
使用 bazel test 运行测试。
用户也可以直接执行测试二进制文件。我们允许这种做法，但不表示认可 因此此类调用将不遵循下述授权。
测试应该是封闭的：也就是说，测试应该只访问这些资源 它们已声明了依赖项如果测试未正确密封，则无法提供可重现历史结果。这可能是 找出导致罪魁祸首的重大问题（确定哪些更改破坏测试）、 发布工程可审核性，以及测试的资源隔离（自动化 测试框架不应对服务器进行 DDOS，因为有些测试正好需要与 ）。
目标
本页的目标是正式建立 Bazel 测试的运行时环境和预期行为。它还会对测试运行程序和构建系统施加要求。
测试环境规范可帮助测试作者避免依赖未指定的行为，从而让测试基础架构能够更自由地进行实现更改。该规范缩小了一些漏洞，目前许多测试虽然未正确实现密封性、确定性和可重入性，但仍能通过测试。
本页面旨在提供规范性和权威性信息。如果此规范与测试运行程序的实现行为不一致，则以规范为准。
拟议规范
关键字“必须”“不得”“必需”“会”“不会”“应” “不应该”“建议”“可以”和“可选”将被解释为 （如 IETF RFC 2119 中所述）。
测试目的
Bazel 测试的目的是确认源文件的某个属性 签入代码库（在此页面上，“源文件”包括测试数据、标准输出以及受版本控制的任何其他内容。）一位用户编写了一项测试，用于断言他们希望保持的不变性。其他用户稍后会执行该测试，以检查是否破坏了不变量。如果测试依赖于源文件以外的任何变量（非密封），其价值会降低，因为当测试停止通过时，后续用户无法确定是他们的更改导致了问题。
因此，测试结果只能取决于以下因素：
- 测试声明了依赖项的源文件
- 已声明测试依赖的构建系统的产品
- 行为由测试运行程序保证保持不变的资源
目前，未强制执行此类行为。不过，测试运行程序保留日后添加此类强制执行措施的权利。
构建系统的角色
测试规则类似于二进制规则，每个规则都必须生成一个可执行文件 计划。对于某些语言，这是一个存根程序，用于将 测试代码。测试规则必须生成 输出内容。除了主要测试可执行文件之外，测试运行程序还需要 runfile 清单，即应在运行时提供给测试的输入文件，并且可能需要测试的类型、大小和标记的相关信息。
构建系统可以使用 runfile 传递代码和数据。（ 可以作为优化措施， 文件。）构建系统 应确保生成的可执行文件通过 runfile 测试运行程序提供的图像，而不是对绝对 在源树或输出树中的位置。
测试运行程序的角色
从测试运行程序的角度来看，每个测试都是一个程序，
使用 execve() 调用。可能还有其他方法可以执行测试；例如，IDE 可能允许在进程中执行 Java 测试。不过，结果
必须被视为权威性测试。如果
测试进程运行至完成并正常终止，并显示退出代码
零，则表示测试已通过。任何其他结果均被视为测试失败。具体而言，将任何字符串 PASS 或 FAIL 写入标准输出对测试运行程序没有意义。
如果测试执行时间过长、超出某些资源限制，或者测试运行程序以其他方式检测到禁止的行为，则可能会选择终止测试并将运行视为失败。在向测试进程或其任何子进程发送信号后，运行程序不得报告测试已通过。
整个测试目标（而非单个方法或测试）有有限的时间来运行到完成。测试的时限取决于其 timeout 属性，具体取决于下表：
| 超时 | 时间限制（秒） |
|---|---|
| 短片 | 60 |
| 适中 | 300 |
| long | 900 |
| 永恒 | 3600 |
未明确指定超时的测试会根据
测试的 size，如下所示：
| 大小 | 隐含的超时标签 |
|---|---|
| 小 | 短片 |
| medium | 适中 |
| 大 | long |
| 巨大 | 永恒 |
“大型”对于没有显式超时设置的测试，将分配 900 秒。如果“中等”测试的超时设置为“短”，则系统会为其分配 60 秒的时间。
与 timeout 不同，size 还会确定在本地运行测试时其他资源（如 RAM）的假设峰值用量，如常见定义中所述。
size 和 timeout 标签的所有组合都是合法的，因此“特大”测试
可以声明超时为“short”。它应该能
很快会发生可怕的事情
无论超时多久，测试都可能会以任意速度返回。测试不会因超长超时而受到处罚，但系统可能会发出警告：通常，您应尽可能缩短超时设置，以免出现任何不稳定的情况。
在已知运行缓慢的情况下手动运行时，可以使用 --test_timeout bazel 标志替换测试超时设置。--test_timeout 值以秒为单位。例如，--test_timeout=120 将测试超时设置为两分钟。
此外，还有一个建议的测试超时下限，如下所示：
| 超时 | 最短时间（秒） |
|---|---|
| 短片 | 0 |
| 适中 | 30 |
| long | 300 |
| 永恒 | 900 |
例如，如果“中等”测试在 5.5 秒内完成，请考虑设置 timeout =
"short" 或 size = "small"。使用 bazel --test_verbose_timeout_warnings 命令行选项会显示指定大小过大的测试。
测试大小和超时时间在 BUILD 文件中根据此处的规范指定。如果未指定，测试的大小将默认为“中等”。
如果测试的主进程退出，但其某些子进程仍在运行，则测试运行程序应视为运行已完成，并根据从主进程观察到的退出代码将其计为成功或失败。测试运行程序可能会终止所有无效进程。测试不应以这种方式泄露进程。
测试分片
测试可以通过测试分片进行并行处理。请参阅
--test_sharding_strategy
和shard_count至
启用测试分片。启用分片后，每个分片都会启动一次测试运行程序。环境变量 TEST_TOTAL_SHARDS 是分片数量，而 TEST_SHARD_INDEX 是分片索引，从 0 开始。运行程序会使用此信息来选择要运行的测试，例如使用轮替策略。并非所有测试运行程序都支持分片。如果运行程序支持分片，则必须创建或更新 TEST_SHARD_STATUS_FILE 指定的文件的上次修改日期。否则，如果
--incompatible_check_sharding_support
启用后，如果 Bazel 被分片，测试将无法通过。
初始条件
在执行测试时，测试运行程序必须建立特定的初始 条件。
测试运行程序必须使用 argv[0] 中测试可执行文件的路径调用每项测试。此路径必须是相对路径，并且位于测试的当前目录（位于 runfiles 树中，见下文）下。测试运行程序不应通过任何
为测试添加其他参数，除非用户明确要求。
初始环境块的构成如下：
| 变量 | 值 | 状态 |
|---|---|---|
HOME |
$TEST_TMPDIR 的值 |
推荐 |
LANG |
unset | 必填 |
LANGUAGE |
unset | 必填 |
LC_ALL |
unset | 必填 |
LC_COLLATE |
unset | 必填 |
LC_CTYPE |
unset | 必填 |
LC_MESSAGES |
unset | 必填 |
LC_MONETARY |
unset | 必填 |
LC_NUMERIC |
unset | 必填 |
LC_TIME |
unset | 必填 |
LD_LIBRARY_PATH |
以冒号分隔的包含共享库的目录列表 | 可选 |
JAVA_RUNFILES |
$TEST_SRCDIR 的值 |
已弃用 |
LOGNAME |
$USER 的值 |
必填 |
PATH |
/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:. |
推荐 |
PWD |
$TEST_SRCDIR/workspace-name |
推荐 |
SHLVL |
2 |
推荐 |
TEST_INFRASTRUCTURE_FAILURE_FILE |
可写目录中某个私有文件的绝对路径（此文件 只能用于报告 而非作为报告不稳定故障的一般机制 测试。在本文档中，测试基础架构是指并非特定于测试的系统或库，但可能会因故障而导致测试失败。第一行是导致失败的测试基础架构组件的名称，第二行是失败的人类可读说明。其他行会被忽略）。 | 可选 |
TEST_LOGSPLITTER_OUTPUT_FILE |
可写目录中私有文件的绝对路径（用于写入 Logsplitter 协议缓冲区日志） | 可选 |
TEST_PREMATURE_EXIT_FILE |
可写目录中不公开文件的绝对路径（用于
捕获对 exit() 的调用） |
可选 |
TEST_RANDOM_SEED |
如果使用 --runs_per_test 选项，
TEST_RANDOM_SEED 设置为 run number
（从 1 开始）。 |
可选 |
TEST_RUN_NUMBER |
如果使用 --runs_per_test 选项，则系统会为每次单独的测试运行将 TEST_RUN_NUMBER 设置为 run number（从 1 开始）。 |
可选 |
TEST_TARGET |
要测试的目标的名称 | 可选 |
TEST_SIZE |
测试 size |
可选 |
TEST_TIMEOUT |
测试 timeout（以秒为单位） |
可选 |
TEST_SHARD_INDEX |
分片编号（如果使用 sharding） |
可选 |
TEST_SHARD_STATUS_FILE |
要触摸的文件路径，用于表示支持 sharding |
可选 |
TEST_SRCDIR |
runfiles 树基底的绝对路径 | 必填 |
TEST_TOTAL_SHARDS |
总计
shard count,
如果使用 sharding |
可选 |
TEST_TMPDIR |
私有可写目录的绝对路径 | 必填 |
TEST_WORKSPACE |
本地代码库的工作区名称 | 可选 |
TEST_UNDECLARED_OUTPUTS_DIR |
私有可写目录的绝对路径（用于写入未声明的
测试输出）。任何写入到
TEST_UNDECLARED_OUTPUTS_DIR 目录将被压缩，
添加到outputs.zip下
bazel-testlogs。 |
可选 |
TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR |
指向私有可写目录的绝对路径（用于写入未声明的测试输出注解 .part 和 .pb 文件）。 |
可选 |
TEST_WARNINGS_OUTPUT_FILE |
可写目录中私有文件的绝对路径（用于写入测试目标警告） | 可选 |
TESTBRIDGE_TEST_ONLY |
值
--test_filter,
（如果指定） |
可选 |
TZ |
UTC |
必填 |
USER |
getpwuid(getuid())->pw_name 的值 |
必填 |
XML_OUTPUT_FILE |
测试操作应将测试结果 XML 输出文件写入到的位置。 否则，Bazel 会生成封装测试日志的默认 XML 输出文件 作为测试操作的一部分。XML 架构基于 JUnit 测试结果架构。 | 可选 |
BAZEL_TEST |
表示测试可执行文件由 bazel test 驱动 |
必填 |
环境可能包含其他条目。测试不应依赖于 上面未列出的任何环境变量的存在、缺失或值。
初始工作目录应为 $TEST_SRCDIR/$TEST_WORKSPACE。
当前的进程 ID、进程组 ID、会话 ID 和父级进程 ID 为 未指定。该进程可以是，也可以不是进程组主进程或会话主进程。进程可以有控制终端，也可以没有。该过程可能会 具有零个或零个或多个正在运行或未回收的子进程。当测试代码获得控制权时，进程不应具有多个线程。
文件描述符 0 (stdin) 应处于打开状态以供读取，但其附加的对象未指定。测试不得从中读取数据。文件描述符 1 (stdout) 和 2
(stderr) 应开放写入，但附加的内容为
未指定。它可以是终端、管道、常规文件或任何其他可以写入字符的对象。他们可能会共享打开文件表中的条目
（这意味着它们不能独立寻找）。测试不应继承任何其他打开的文件描述符。
初始 umask 应为 022 或 027。
不得有待处理的闹钟或间隔定时器。
被屏蔽信号的初始掩码应为空。所有信号都应设置为其默认操作。
初始资源限制（软限制和硬限制）应设置如下：
| 资源 | 限制 |
|---|---|
RLIMIT_AS |
无限制 |
RLIMIT_CORE |
未指定 |
RLIMIT_CPU |
无限制 |
RLIMIT_DATA |
无限制 |
RLIMIT_FSIZE |
无限制 |
RLIMIT_LOCKS |
无限制 |
RLIMIT_MEMLOCK |
无限制 |
RLIMIT_MSGQUEUE |
未指定 |
RLIMIT_NICE |
未指定 |
RLIMIT_NOFILE |
至少 1024 |
RLIMIT_NPROC |
未指定 |
RLIMIT_RSS |
无限制 |
RLIMIT_RTPRIO |
未指定 |
RLIMIT_SIGPENDING |
未指定 |
RLIMIT_STACK |
无限制，或 2044KB <= rlim <= 8192KB |
初始进程时间（由 times() 返回）和资源利用率（由 getrusage() 返回）未指定。
初始调度政策和优先级未指定。
主机系统的角色
除了测试运行程序直接控制的用户上下文方面之外，测试执行所在的操作系统还必须满足特定属性，测试运行才有效。
文件系统
测试观察到的根目录不一定是真实的根目录。
应装载 /proc。
所有构建工具都应位于/usr
本地安装
以 /home 开头的路径可能不可用。测试不应访问任何此类路径。
/tmp 应可写入，但测试应避免使用这些路径。
测试不得假定任何常量路径可供其独占使用。
测试不得假设已为任何已装载的文件系统启用 atime。
用户和组
users root、nobody 和 unittest 必须存在。群组 root、nobody 和 eng 必须存在。
必须以非根用户身份执行测试。真实用户 ID 和有效用户 ID 必须相同；群组 ID 也是如此。除此之外，当前的用户 ID、群组 ID、 用户名和群组名称均未指定未指定一组补充组 ID。
当前的用户 ID 和组 ID 必须有相应的名称，
使用 getpwuid() 和 getgrgid() 进行检索。补充组 ID 可能不适用。
当前用户必须有一个主目录。它可能无法写入。测试必须 请勿尝试对其进行写入。
网络
未指定主机名。它可以包含或不包含英文句点。解决 主机名必须提供当前主机的 IP 地址。解析第一个点后截断的主机名也必须可行。localhost 必须解析主机名。
其他资源
系统会向测试授予至少一个 CPU 核心。也可能有其他方法，但我们无法保证。未指定此核心的其他性能方面。您可以 通过添加标记将预留增加到更多 CPU 核心数 "cpu:n"（其中 n 为正数）。如果机器的 CPU 核心总数少于请求的数量，Bazel 仍会运行测试。如果测试使用分片，则每个分片都会预留此处指定的 CPU 核心数量。
测试可以创建子进程，但不能处理组或会话。
测试可使用的输入文件数量有限。此限制为 可能会有变化，但目前在数万个输入范围内。
时间和日期
未指定当前时间和日期。未指定系统时区。
X Windows 可能可用，也可能不可用。需要 X 服务器的测试应启动 Xvfb。
测试与文件系统的交互
除非另有说明，否则测试环境变量中指定的所有文件路径都指向本地文件系统中的某个位置。
测试应仅在 $TEST_TMPDIR 和 $TEST_UNDECLARED_OUTPUTS_DIR（如果已设置）指定的目录中创建文件。
这些目录最初为空。
测试不得尝试移除、chmod 或以其他方式更改这些目录。
这些目录可能是符号链接。
$TEST_TMPDIR/. 的文件系统类型仍然未指定。
测试还可以将 .part 文件写入 $TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR，以注释未声明的输出文件。
在极少数情况下，测试可能会被迫在 /tmp 中创建文件。例如，Unix 域套接字的路径长度限制通常要求在 /tmp 下创建套接字。Bazel 将无法跟踪此类文件；测试本身必须注意保持密封性，使用唯一的路径以避免与其他同时运行的测试和非测试进程冲突，并清理它在 /tmp 中创建的文件。
一些常用的测试框架，例如
JUnit4 TemporaryFolder
或 Go TempDir，
用自己的方式在 /tmp 下创建临时目录。这些测试
框架包含清理 /tmp 中的文件的功能，因此您可以使用
即使他们在 TEST_TMPDIR 之外创建文件，也是如此。
测试必须通过 runfiles 机制或执行环境的其他部分（专门用于提供输入文件）访问输入。
测试不得通过从其自身可执行文件的位置推断出的路径访问构建系统的其他输出。
不指定 runfiles 树是否包含符号
链接或两者的组合。runfile 树可能包含指向目录的符号链接。测试应避免在 runfile 中使用包含 .. 组成部分的路径
树。
runfiles 树中没有任何目录、文件或符号链接（包括
遍历符号链接）。（因此，最初的工作是
目录。）测试不得假定运行文件的任何部分都是可写的，或者归当前用户所有（例如，chmod 和 chgrp 可能会失败）。
在测试执行期间，runfile 树（包括遍历符号链接的路径）不得更改。不得更改父级目录和文件系统装载 以任何方式影响运行文件中某个路径的解析结果 树。
为了捕获提前退出，测试可能会在启动时在 TEST_PREMATURE_EXIT_FILE 指定的路径中创建文件，并在退出时将其移除。如果 Bazel
文件，则会认为测试过早退出，
将其标记为已失败
代码规范
测试规则中的某些标记具有特殊含义。另请参阅 Bazel Build 百科全书中的 tags 属性。
| 标记 | 含义 |
|---|---|
exclusive |
不同时运行其他测试 |
external |
测试具有外部依赖项；停用测试缓存 |
large |
test_suite 惯例；大型测试套件 |
manual * |
请勿在通配符目标格式中包含测试目标，例如
:...、:* 或 :all |
medium |
test_suite 惯例；一组中等测试 |
small |
test_suite 惯例；一套小型测试 |
smoke |
test_suite 惯例；意味着它应该在
将代码更改提交到版本控制系统 |
runfile
在下例中，假设有一条 *_binary() 规则，
//foo/bar:unittest，运行时依赖于标记为
//deps/server:server。
位置
目标 //foo/bar:unittest 的 runfiles 目录为 $(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles 目录。该路径称为
runfiles_dir。
依赖项
runfiles 目录被声明为 *_binary() 规则的编译时依赖项。runfiles 目录本身依赖于 BUILD 文件集
影响 *_binary() 规则或其任何编译时或运行时的文件
依赖项修改源文件不会影响
runfiles 目录，因此不会触发任何重新构建。
目录
runfiles 目录包含以下内容：
- 指向运行时依赖项的符号链接：每个 OutputFile 和 CommandRule 都是
*_binary()规则的运行时依赖项，由 runfiles 目录中的一个符号链接表示。符号链接的名称为$(WORKSPACE)/package_name/rule_name。例如，服务器的符号链接将命名为$(WORKSPACE)/deps/server/server，完整路径为$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server。符号链接的目标是 OutputFile 或 CommandRule，表示为绝对路径。因此，符号链接的目标可能为$(WORKSPACE)/linux-dbg/deps/server/42/server。 - 子运行时的符号链接：针对运行时的每个
*_binary()Z*_binary()C 的依赖项，则 runfile 中还有第二个链接 复制到 Z 的 runfile 中。符号链接的名称为$(WORKSPACE)/package_name/rule_name.runfiles。符号链接的目标是 runfiles 目录。例如，所有子程序共享一个通用的 runfiles 目录。