测试执行环境的详尽规范。
背景
Bazel 构建语言包括一些规则，可用于定义多种语言的自动测试程序。
使用 bazel test 运行测试。
用户也可以直接执行测试二进制文件。这种行为是允许的，而不是背书，因为这种调用不遵循下述要求。
测试应该是封闭测试，也就是说，测试应该只访问声明了依赖项的那些资源。如果测试没有封闭的凭据，它们将无法提供过去可重现的结果。这可能是严重的问题（导致您确定更改会破坏测试）、发布工程可审核性和测试资源隔离（自动测试框架不应 DDOS 服务器，因为有些测试会恰好发生）。
目标
本页的目标是正式建立 Bazel 测试的运行时环境和预期行为。它还会对测试运行程序和构建系统施加要求。
测试环境规范可以帮助测试作者避免依赖于未指定的行为，因此可以让测试基础架构更自由地在实现方面进行更改。此规范扩大了一些漏洞，目前允许许多测试在未适当封闭、确定和可重入的情况下通过。
本页面应既具规范性又具有权威性。如果此规范与测试运行程序实现的行为不一致，则以规范为准。
建议的规范
关键词“必须”“不得”“必需”“会”“不会”“应”“不应”“建议”“可以”和“可选”会按照 IETF RFC 2119 中的说明进行解释。
测试目的
Bazel 测试的目的是确认签入代码库的源文件的某些属性。（在此页面上，“源文件”包括测试数据、黄金输出和所有其他版本控制内容）。一位用户编写了一个测试，以断言其要维护的不变。其他用户稍后会执行测试，检查不可变是否已损坏。如果测试依赖于除源文件以外的任何变量（非封闭），则其值会减少，因为后面的用户无法保证在测试停止时他们的更改出现问题。
因此，测试结果只能依赖于：
- 测试声明的依赖项
- 测试具有声明的依赖项的构建系统的产品
- 由测试运行程序保证其行为保持不变的资源
目前，此类行为不会强制执行。不过，测试运行程序保留未来添加此类强制执行的权利。
构建系统的作用
测试规则类似于二进制规则，因为每条规则都必须生成可执行程序。对于某些语言，这是一个存根程序，将特定于语言的自动化测试框架与测试代码结合在一起。测试规则还必须生成其他输出。除了主要测试可执行文件之外，测试运行程序还需要一个包含 runfiles 的清单、应在运行时提供给测试的输入文件，并且可能需要有关测试的类型、大小和标记的信息。
构建系统可以使用运行文件来交付代码和数据。（这样可以用作优化措施，通过在测试之间共享文件（例如通过使用动态链接）来缩减每个测试二进制文件。）构建系统应确保生成的可执行文件通过测试运行程序提供的 runfiles 映像（而不是对源代码树或输出树中的绝对位置进行硬编码）加载这些文件。
测试运行程序的角色
从测试运行程序的角度来看，每个测试都是一个可通过 execve() 调用的程序。也可以通过其他方式执行测试；例如，IDE 可能会允许执行中的 Java 测试。但是，将测试作为独立进程运行的结果必须被视为权威结果。如果测试进程运行完成，并在退出代码结束时正常终止，则表示已通过测试。任何其他结果都被视为测试失败。特别是，将任何字符串 PASS 或 FAIL 写入 stdout 对测试运行程序没有任何意义。
如果测试的执行时间过长、超出某个资源限制或者测试运行程序检测到其他禁止的行为，则可能会选择终止测试并将运行视为失败。向测试进程或其任何子节点发送信号后，运行程序不得将测试报告为通过。
整个测试目标（而不是具体方法或测试）的运行时间有限。测试的时间限制基于其 timeout 属性，如下表所示：
| 超时 | 时间限制（秒） |
|---|---|
| 短片 | 60 |
| 适中 | 300 |
| long | 900 |
| 永恒 | 3600 |
没有明确指定超时的测试将根据测试的 size 包含一个隐式查询，如下所示：
| 大小 | 隐式超时标签 |
|---|---|
| small | 短片 |
| medium | 适中 |
| 大 | long |
| 巨大 | 永恒 |
没有明确超时设置的“大型”测试将分配 900 秒的时间。超时为“short”的“中”测试将分配 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 目录的文件都将被压缩并添加到 bazel-testlogs 下的 outputs.zip 文件中。 |
可选 |
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 |
至少 1,024 |
RLIMIT_NPROC |
未指定 |
RLIMIT_RSS |
无限制 |
RLIMIT_RTPRIO |
未指定 |
RLIMIT_SIGPENDING |
未指定 |
RLIMIT_STACK |
无限制，或 2044KB <= rlim <= 8192KB |
初始处理时间（由 times() 返回）和资源利用率（由 getrusage() 返回）未指定。
初始调度政策和优先级未指定。
主机系统的角色
除了直接控制测试运行程序的用户情境之外，执行测试的操作系统还必须满足某些属性，才能让测试运行有效。
文件系统
测试观察到的根目录不一定是实际的根目录。
应装载 /proc。
所有构建工具都应位于本地安装所用的 /usr 下的绝对路径下。
以 /home 开头的路径可能不可用。测试不应访问任何此类路径。
/tmp 应该可以写入，但测试应避免使用这些路径。
测试不得假设任何常量路径可供其专用。
测试不得假设已为所有装载的文件系统启用时间。
用户和群组
根用户、无人和单元测试必须存在。组根目录、无人和 eng 必须存在。
测试必须以非根用户身份执行。真实有效的用户 ID 必须相等；群组 ID 也是如此。除此之外，当前用户 ID、群组 ID、用户名和群组名称均未指定。未指定一组补充组 ID。
当前用户 ID 和群组 ID 必须具有相应的名称，可通过 getpwuid() 和 getgrgid() 进行检索。补充组 ID 可能也是如此。
当前用户必须拥有主目录。这项数据可能无法写入。测试不得尝试向其中写入内容。
网络
主机名未指定。不一定包含点。解析主机名时，必须提供当前主机的 IP 地址。解析第一个点之后的主机名也必须可以解决。主机名 localhost 必须进行解析。
其他资源
测试被授予至少一个 CPU 核心。其他选项可能也可用，但无法保证此操作。此核心的其他性能方面未指定。您可以通过向测试规则添加“cpu:n”标记（其中 n 为正数）来将预留增加到更多 CPU 核心。即使机器的 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 树是包含常规文件、符号链接，还是混合。runfiles 树可能包含指向目录的符号链接。测试应避免在 runfiles 树中使用包含 .. 组件的路径。
runfiles 树中的目录、文件或符号链接（包括遍历符号链接的路径）不应可写入。（由此可见，初始工作目录应不可写。）测试不得假定任何运行文件的任何部分可写入或归当前用户所有（例如，chmod 和 chgrp 可能失败）。
runfiles 树（包括遍历符号链接的路径）在测试执行期间不得更改。父目录和文件系统装载不得以任何影响 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 惯例；表示先运行代码，然后再将代码更改提交到版本控制系统 |
运行文件
在下例中，假设有一条标记为 //foo/bar:unittest 的 *_binary() 规则，且对 //deps/server:server 规则的规则有运行时依赖关系。
位置
目标 //foo/bar:unittest 的 runfiles 目录是 $(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles 目录。此路径称为 runfiles_dir。
依赖项
runfiles 目录声明为 *_binary() 规则的编译时依赖项。runfiles 目录本身依赖于一组 BUILD 文件，这会影响 *_binary() 规则或其任何编译时或运行时依赖项。修改源文件不会影响运行文件目录的结构，因此不会触发任何重新构建操作。
目录
runfiles 目录包含以下内容：
- 运行时依赖项的符号链接：属于
*_binary()规则运行时依赖项的每个 OutputFile 和 CommandRule 都由 runfiles 目录中的一个符号链接表示。符号链接的名称为$(WORKSPACE)/package_name/rule_name。例如，服务器的符号链接将命名为$(WORKSPACE)/deps/server/server，完整路径将为$(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server。符号链接的目的地是 OutputFile 或 CommandRule 的 OutputFileName()，以绝对路径的形式表示。因此，符号链接的目的地可能是$(WORKSPACE)/linux-dbg/deps/server/42/server。 - 指向子运行文件的符号链接：对于
*_binary()*_binary()C 的运行时依赖项，每个*_binary()Z 都存在指向 C 的 runfiles 目录中的第二个链接。符号链接的名称为$(WORKSPACE)/package_name/rule_name.runfiles。符号链接的目标为 runfiles 目录。例如，所有子程序都共享一个共同的 runfiles 目录。