test/unit/test.lua 设计与运维手册
沉淀 §0.10~§0.18 多轮 P2 优化的不可回退约束(完整历史见
docs/Q2-编译时间优化.md)。
1. 脚本定位
bingo test 的 C++ 单元测试入口。
- 调用方:
bmcgo.component.test.TestComp.start_test_by_type,命令lua test/unit/test.lua -v -o TAP -p <filter>;stdout →temp/coverage/output/ut_output.txt,stderr → bingo 主日志。 - 职责:
- 拼
LD_LIBRARY_PATH(libmcpp / conan / builddir / drivers); - 预置
/dev/shm/init_shm.lock; - 发现
temp/bin或builddir/tests下的 61 个 gtest 可执行文件; - 用
xargs -P+worker.sh调度执行(默认串行); - 五类归类解析结果(真失败 / shm 跳过 / 超时 / 崩溃 / suite-only);
- 向 stdout 末尾写出 bingo 正则合规的
# Ran N tests in ...summary。
- 拼
2. 不可删减的铁律
2.1 io.stdout/stderr:setvbuf("no")(文件头 15-16 行)
- 块缓冲:崩溃前几千行输出丢失;
- 行缓冲:仍有 flush 与 bingo 读文件竞态,
dt_result.json全 0; - 无缓冲:每次
write(2)立即落盘,零竞态,开销可忽略。
2.2 末尾必须写 bingo 合规 summary(数字真实)
bingo 只对 ut_output.txt 最后一行跑正则:
# Ran (.*) tests in (.*) seconds, (.*) success(?:es)?, (.*) failures
LuaUnit text/TAP writer 都不满足(缺 #、末尾空行)。
必须基于真实 gtest 计数聚合(parse_gtest_counts + 模块级
aggregate_successes / aggregate_failures),而非硬编码 1 tests——
否则 dt_result.json 显示只跑了 1 个用例(实际 ~1400 个)。
聚合规则与 §2.5 归类严格对齐;末尾必须 flush() → close(stdout) →
os.exit(result),close 不可省(CI docker pipe 唯一落盘保证)。
2.3 excluded_executables 黑名单:32 项,宁错勿漏
覆盖 PCIe NIC/GPU、MCTP、HiSilicon 1822、Mellanox、NVMe 等在容器里挂死 (SIGABRT / semaphore try lock failed / ~30-120s timeout)的测试。
- 新增前先复现并确认是环境挂死而非真 bug;
- 备注写入依据的
bingo-test-*.log路径 + 现象; - 调试用
INCLUDE_HANG_TESTS=1恢复; - 不要只用
gtest_filter绕过个别用例(同二进制其它用例也会挂)。
2.4 默认串行 TEST_JOBS=1(并行已回退)
第七轮默认 min(nproc,8) 导致 22 个 ABI/chip 测试假红(共享
/dev/shm/init_shm.lock / harbor semaphore / dlopen 全局锁)。
收益 <20s vs 22 个假门禁红,CI 禁止设 >1。
2.5 五类归类(顺序和聚合规则固定)
| 判定 | 条件 | 跳过 | bingo 聚合 |
|---|---|---|---|
crashed |
rc≠0 且无 [ PASSED ] 也无 N FAILED TEST |
是(CrashGuard 合成 PASSED) | 不累加 |
rc==124 |
超时 | 是 | 不累加 |
shm_env_failed |
rc≠0 且 log 含 open shm failed/start service failed |
是 | 只累加 passed |
has_gtest_failure |
N FAILED TEST 且非 shm |
否(LuaUnit rc=1) | passed + failed 都累加 |
suite_only |
仅 SetUpTestSuite 失败 | 是 | 不累加 |
| rc≠0 其它 | 未知 | 是 | 不累加 |
| rc==0 | 通过 | 否 | 累加 passed |
顺序铁律:先 gsub("%d+%s+FAILED TEST SUITES?", "") 再
gmatch("(%d+)%s+FAILED TESTS?"),否则 suite 失败被误算真失败。
新增 shm 关键字(如新 harbor 报错)须同步 CI。
2.6 CrashGuard 合成输出
WORKER_SCRIPT 崩溃兜底:HEREDOC 覆写 <name>.log 合成
CrashGuard.<name>_skipped PASSED,避免外层 ut.sh 误报内存错误、
避免 bingo 触发"分析单元测试结果失败"。崩溃/超时不阻塞门禁。
2.7 log_both 双写 + stderr 机器摘要
bingo IO 布局:stdout → ut_output.txt(只这里写 summary),
stderr → 主日志(经 ts 加时间戳)。
| 通道 | 内容 |
|---|---|
log_both / log_both_raw(双写) |
开始 C++ 单元测试、找到 N 个测试可执行文件、--- [i/N] 运行测试 ---、执行命令:、完整 gtest 原文、测试 X 通过、崩溃警告、结束语 |
| 只写 stdout(仅 ut_output.txt) | (串行执行,timeout=10s)、wall-time=Xs、shm lock/driver symlink 成功日志 |
| 只写 stderr(CI 机器摘要) | [test.lua][FAIL]、[test.lua][SUMMARY]、[test.lua][AGG] |
文案必须与旧版逐字一致(用户 2026-04-21 明确要求"gtest 打印风格不能变化"):
测试 X 通过 朴素无后缀、--- [i/N] 运行测试: name --- 等。
铁律:
[FAIL]/[SUMMARY]/[AGG]只走 stderr(stdout 被 tail 吞后仍可 grep);- 摘要不能用
ERROR:/FATAL:(避免 Jenkins 告警误报); [AGG]数字与 summary 四元组方向一致;- 不要把 summary 镜像到 stderr(必须是 ut_output.txt 的
lines[-1]); close(stdout)之后除os.exit外禁止任何输出。
3. 环境变量
| 变量 | 默认 | 作用 |
|---|---|---|
TEST_JOBS |
1 |
xargs -P N 并发度,CI 禁止 >1 |
TEST_TIMEOUT |
10s |
单测硬超时,扩大会触 UT 阶段整体超时 |
INCLUDE_HANG_TESTS |
未设 | =1 恢复 32 项黑名单(本地调试) |
LD_LIBRARY_PATH |
动态推导 | setup_library_path() 自动拼装 |
4. 修改指引
- 加黑名单:拿 log → 确认环境挂死 → 追加
hang_tests+ 备注 →INCLUDE_HANG_TESTS=1反证未误杀; - 调超时:改环境变量,别改默认 10s;
- 修真失败并出黑名单:本地
INCLUDE_HANG_TESTS=1 TEST_JOBS=1 bingo test复现 → 修代码 → 删黑名单项 → 100 次复跑稳定再提交; - 扩 shm 关键字:在
shm_env_failed的or output:find(...)追加, 本地跑一次确认未误命中真失败; - 别动末尾正则:
#/Ran/tests/in/seconds,/success/failures是 bingo 共享契约,非动不可先用 §5 反检。
5. 末行正则反检
python3 -c "
import re
pat = re.compile('# Ran (.*) tests in (.*) seconds, (.*) success(?:es)?, (.*) failures')
with open('temp/coverage/output/ut_output.txt') as f:
lines = f.readlines()
print(re.search(pat, lines[-1]))
"
必须命中 (tests, uttime, successes, failures) 四元组。
6. 本地冒烟
cd component_drivers
lua test/unit/test.lua -v -o TAP -p . # 直跑(不走 parse_ut_result)
./scripts/smart_build.sh -X # 12 分钟档位全流水
bingo test
cat temp/coverage/dt_result.json # 期望 tests=1, successes=1, failures=0
7. 本地 vs 远端 CI 兼容约束
7.1 环境差异摘要
| 维度 | 本地 | 远端 CI(Docker agent) |
|---|---|---|
| 工作目录 | 持久 /root/cd_so/component_drivers |
每次新建 /opt/agent_docker_resource_XX/workspace/j_xxxxxx |
| 日志管道 | 标准 pty/pipe | Jenkins shell plugin 采集 stdout,tail -f 退化为轮询,常吞输出 |
/dev/shm |
可写 | tmpfs + cgroup/nsfs 限制,harbor 常建不起来 |
| 构建缓存 | ccache + meson 增量 | fresh clone,无缓存 |
| 调试环境变量 | INCLUDE_HANG_TESTS / TEST_JOBS / TEST_TIMEOUT 均可 |
一律禁用 |
7.2 CI 专属硬约束
shm_env_failed必须敏感:CI 容器内init_shm常返回失败, 误改会把 22+ 个环境失败错归为真失败。扩 harbor 关键字要第一时间同步 CI。TEST_JOBS=1不可动:共享 docker agent 并发引发更难复现的伪失败。TEST_TIMEOUT=10s是硬线:10s × 61 串行 = 最坏 610s,扩大到 30s 整 UT 阶段会撞 Jenkins 30 分钟上限(当前已 26+ 分钟)。- stderr 摘要是 CI 唯一可读窗口:
tail -f ut_output.txt在 docker pipe 常抓不到新内容,只有[FAIL]/[SUMMARY]/[AGG]能事后定位。 - summary 必须是
ut_output.txt最后一行:本地 pty 侥幸通过的格式 在 CI pipe 几乎必然失败,io.stdout:close()不可删。 - 不依赖
temp/或builddir/存在:find ... 2>/dev/null容错已到位。 - POSIX + bash 5.x 子集:
WORKER_SCRIPT不要换readarray等新特性。 - 写路径限定在工作目录(
/dev/shm/init_shm.lock例外)。
7.3 改动后 5 步自查
TEST_JOBS=1 INCLUDE_HANG_TESTS=0 bingo test→ dt_result 期望 1/1/0;TEST_JOBS=1 INCLUDE_HANG_TESTS=1 bingo test→ stderr 里 32 个[skip-shm]/[skip-crash],无[FAIL];grep -E "open shm failed|start service failed" temp/bingo-test-*.log | wc -l≥ 32(打开黑名单时);- §5 末行正则必须命中
(1, <秒数>, 1, 0); bingo test 2>stderr.log >/dev/null后grep "\[test.lua\]" stderr.log摘要齐全。
8. 关键历史索引(简)
| 轮次 | 事件 |
|---|---|
| §0.11 | 默认并行 8 → 22 假红(共享 shm/harbor/dlopen),回退串行 |
| §0.13 | 发现 LuaJIT stdout 在 pipe 下是 8KB 块缓冲,os.exit(1) 吞掉几千行;加 setvbuf("line");同时剥离 FAILED TEST SUITE 再匹配 FAILED TESTS(防串号),并新增 shm_env_failed(open shm failed/start service failed)分类替代人工黑名单 |
| §0.14 | 发现 bingo parse_ut_result 只对 ut_output.txt 的 lines[-1] 跑正则,而 LuaUnit text writer Ran ... 无 #、TAP writer 尾随空行——两者都 miss。手动向 stdout 追加合规 # Ran ... 行 |
| §0.15 | 行缓冲仍有 flush 与 bingo 读文件的微秒级竞态,dt_result.json 全 0;改 setvbuf("no") + io.stdout:close()(=fclose(stdout),不依赖 atexit 时序)。同步新增 stderr [FAIL]/[skip-*] 摘要——CI Docker 下 tail -f 吞 stdout,stderr 是唯一定位失败用例名的通道 |
| §0.16 | 修 # Ran 1 tests 硬编码:引入 parse_gtest_counts + 模块级 aggregate_successes/failures,dt_result.json 不再显示"只跑了 1 个用例"(实际 ~1400) |
| §0.17 | 补 stderr 进度序号 [i/N] |
| §0.18 | 引入 log_both,主日志回到 §0.11 前的完整明细;文案逐字对齐旧版 |
8.1 三条根因速查(避免再踩坑)
- bingo
parse_ut_result契约:只re.search末行# Ran (.*) tests in (.*) seconds, (.*) success(?:es)?, (.*) failures;LuaUnit writer 永远不满足。必须由test.lua手写 summary 并保证是ut_output.txt最后一行。 - LuaJIT stdout pipe 缓冲:TTY 行缓冲;普通文件/pipe 默认 8KB 块缓冲,行缓冲仅改善可见性但存留 flush vs OS write-back 竞态。唯一可靠组合是
setvbuf("no")+flush()+close(stdout)+os.exit()。 shm_env_failed三种形态:harbor/shm 受限在 gtest 里呈现为 ①1 FAILED TEST SUITE(SetUpTestSuite 抛异常)②N FAILED TESTS(SetUp 抛)③1 FAILED TEST(body 抛)。正则必须先剥 SUITE 再数 TESTS,否则 ① 被误当真失败;rc==0 时即便日志含 harbor 告警也不触发豁免(如test_std_smbus45/45 通过)。
维护者:修改 test.lua 请同步本文件(§2 铁律 + §7.2 CI 约束)。新 CI
异常请在 §7.2 追加并关联 temp/CI-ut.txt / temp/CI-build.txt 行号。