如何用 GTEST_TOTAL_SHARDS 与 GTEST_SHARD_INDEX 把 GoogleTest 测试函数分发到多台机器并行运行

如何用 GTEST_TOTAL_SHARDS 与 GTEST_SHARD_INDEX 把 GoogleTest 测试函数分发到多台机器并行运行

【免费下载链接】googletestGoogleTest - Google Testing and Mocking Framework项目地址: https://gitcode.com/GitHub_Trending/go/googletest

当测试程序里的测试函数较多、在一台机器上跑完需要很长时间时，可以把同一个测试程序分发到多台机器上并行运行。GoogleTest 官方文档（docs/advanced.md 的 “Distributing Test Functions to Multiple Machines” 一节）把这种技术称为sharding，每台机器叫一个shard。做法是：在各台机器启动测试程序前设置GTEST_TOTAL_SHARDS与GTEST_SHARD_INDEX两个环境变量，GoogleTest 检测到这两个变量后会自动挑选一个测试函数子集来运行，跨所有分片，程序中的每个测试函数恰好运行一次。无需修改任何测试代码。

需要明确一点：机器分配、进程启动与结果收集都由你的测试运行器（test runner）负责，这部分不属于 GoogleTest；GoogleTest 只负责在看到环境变量后选择本机该跑哪些测试。

前提条件

• 已经有一个可执行的 GoogleTest 测试程序。构建方式参见 CMake 快速上手：在CMakeLists.txt中声明对 GoogleTest 的依赖后执行：

  cmake -S . -B build cmake --build build

  构建完成后可得到测试二进制文件（快速上手文档中的示例名为hello_test）。

• 有 N 台可以运行这个二进制文件的机器（N 即分片总数）。

• 各机器能设置环境变量并在启动测试程序时让这些变量生效。

设置分片环境变量

两个变量的取值要求（均来自 docs/advanced.md）：

以 3 台机器为例，在每台机器上启动同一个测试程序（以下命令为 Unix shell 写法，./build/hello_test是 CMake 快速上手文档 中的示例构建产物，请替换为你自己的测试二进制路径）：

# 机器 1 GTEST_TOTAL_SHARDS=3 GTEST_SHARD_INDEX=0 ./build/hello_test # 机器 2 GTEST_TOTAL_SHARDS=3 GTEST_SHARD_INDEX=1 ./build/hello_test # 机器 3 GTEST_TOTAL_SHARDS=3 GTEST_SHARD_INDEX=2 ./build/hello_test

关键点：三台机器运行的是同一个测试程序，GTEST_TOTAL_SHARDS三处相同（都是 3），GTEST_SHARD_INDEX分别是 0、1、2。

文档用一个包含 5 个测试函数的程序foo_test说明了分发效果（文档示例）：

TEST(A, V) TEST(A, W) TEST(B, X) TEST(B, Y) TEST(B, Z)

在 3 台机器上设置GTEST_TOTAL_SHARDS=3、GTEST_SHARD_INDEX分别为 0、1、2 后，每台机器运行同一个foo_test。文档说明 GoogleTest 保留更改跨分片任务划分方式的权利，并给出一种可能的划分示例：

• Machine #0 运行A.V和B.X。
• Machine #1 运行A.W和B.Y。
• Machine #2 运行B.Z。

这只是文档展示的一种可能场景，不要把它当成固定规则，也不要依赖某个测试函数一定落在某台机器上。

验证分片已生效

分片运行时，测试程序的控制台输出会包含一行分片标记，标明当前运行的是第几个分片。仓库官方的输出测试 googletest-output-test.py 就是用GTEST_SHARD_INDEX=1、GTEST_TOTAL_SHARDS=2并附加--gtest_filter=PassingTest.*来验证这一点的，其预期输出文件 googletest-output-test-golden-lin.txt（文档示例）中包含：

Note: Google Test filter = PassingTest.* Note: This is test shard 2 of 2. [==========] Running 1 test from 1 test suite. ... [ RUN ] PassingTest.PassingTest2 [ OK ] PassingTest.PassingTest2 ... [==========] 1 test from 1 test suite ran. [ PASSED ] 1 test.

据此可以按两个维度核对：

1. 输出中出现Note: This is test shard X of Y.标记，说明该进程确实以分片模式运行，且编号与你设置的环境变量一致；
2. 汇总所有分片各自运行的测试，并集应等于测试程序的全部测试函数，且每个测试函数只出现一次——这正是文档对分片语义的承诺。

判断测试程序是否支持分片

如果你的项目里混有未基于 GoogleTest 编写、因此不理解这套协议的测试，文档给出的探测方式是：测试运行器把环境变量GTEST_SHARD_STATUS_FILE设置为一个不存在的文件路径再启动测试程序。支持分片的测试程序会创建这个文件来声明自己支持该协议，不支持的程序则不会创建它。文档说明该文件的实际内容目前不重要（将来可能写入有用信息）。

收集各分片的结果

分片流程的最后一步是：等待所有分片结束后，收集并汇报结果。如果需要机器可读的报告，docs/advanced.md 的 “Generating an XML Report” 一节给出方法：把GTEST_OUTPUT环境变量或--gtest_output标志设置为"xml:path_to_output_file"，GoogleTest 会在指定位置生成 XML 报告，报告包含每个测试的耗时，可用于识别慢测试；只写"xml"时会输出到当前目录的test_detail.xml。由于各分片运行的是同一个程序，收集阶段建议为不同分片指定不同的报告路径，以便区分各机器的结果。

另外，在测试代码内如需判断某个测试是否属于其他分片，可以使用 TestInfo::is_in_another_shard()：当该测试应运行在另一个分片上（即本进程不会运行它）时返回 true。

限制与边界

• 分片的调度粒度是测试函数，不是断言或测试套件内的单个步骤；GoogleTest 选择的是测试函数子集。
• GoogleTest 保留更改跨分片任务划分方式的权利，不要把某个测试函数与某台机器的对应关系当作稳定约定。
• 机器的分配、测试进程的启动、等待全部完成后收集结果，这些环节都由你的测试运行器实现；GoogleTest 本身不管理机器与进程。
• 只有基于 GoogleTest 构建的测试程序才理解这两个环境变量；不支持的测试程序不会自动分片，可用GTEST_SHARD_STATUS_FILE探测。

完成上述配置后，你在每台机器上直接运行同一测试程序，控制台出现Note: This is test shard X of Y.标记、且各分片运行的测试合起来恰好覆盖全部测试函数，就说明分片分发已按预期生效。

【免费下载链接】googletestGoogleTest - Google Testing and Mocking Framework项目地址: https://gitcode.com/GitHub_Trending/go/googletest