FilesLast commitLast update
3 months ago
1 month ago
README

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 主日志。
  • 职责:
    1. 拼 LD_LIBRARY_PATH(libmcpp / conan / builddir / drivers);
    2. 预置 /dev/shm/init_shm.lock;
    3. 发现 temp/bin 或 builddir/tests 下的 61 个 gtest 可执行文件;
    4. 用 xargs -P + worker.sh 调度执行(默认串行);
    5. 五类归类解析结果(真失败 / shm 跳过 / 超时 / 崩溃 / suite-only);
    6. 向 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 专属硬约束

  1. shm_env_failed 必须敏感:CI 容器内 init_shm 常返回失败, 误改会把 22+ 个环境失败错归为真失败。扩 harbor 关键字要第一时间同步 CI。
  2. TEST_JOBS=1 不可动:共享 docker agent 并发引发更难复现的伪失败。
  3. TEST_TIMEOUT=10s 是硬线:10s × 61 串行 = 最坏 610s,扩大到 30s 整 UT 阶段会撞 Jenkins 30 分钟上限(当前已 26+ 分钟)。
  4. stderr 摘要是 CI 唯一可读窗口:tail -f ut_output.txt 在 docker pipe 常抓不到新内容,只有 [FAIL]/[SUMMARY]/[AGG] 能事后定位。
  5. summary 必须是 ut_output.txt 最后一行:本地 pty 侥幸通过的格式 在 CI pipe 几乎必然失败,io.stdout:close() 不可删。
  6. 不依赖 temp/ 或 builddir/ 存在:find ... 2>/dev/null 容错已到位。
  7. POSIX + bash 5.x 子集:WORKER_SCRIPT 不要换 readarray 等新特性。
  8. 写路径限定在工作目录(/dev/shm/init_shm.lock 例外)。

7.3 改动后 5 步自查

  1. TEST_JOBS=1 INCLUDE_HANG_TESTS=0 bingo test → dt_result 期望 1/1/0;
  2. TEST_JOBS=1 INCLUDE_HANG_TESTS=1 bingo test → stderr 里 32 个 [skip-shm]/[skip-crash],无 [FAIL];
  3. grep -E "open shm failed|start service failed" temp/bingo-test-*.log | wc -l ≥ 32(打开黑名单时);
  4. §5 末行正则必须命中 (1, <秒数>, 1, 0);
  5. 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 三条根因速查(避免再踩坑)

  1. bingo parse_ut_result 契约:只 re.search 末行 # Ran (.*) tests in (.*) seconds, (.*) success(?:es)?, (.*) failures;LuaUnit writer 永远不满足。必须由 test.lua 手写 summary 并保证是 ut_output.txt 最后一行。
  2. LuaJIT stdout pipe 缓冲:TTY 行缓冲;普通文件/pipe 默认 8KB 块缓冲,行缓冲仅改善可见性但存留 flush vs OS write-back 竞态。唯一可靠组合是 setvbuf("no") + flush() + close(stdout) + os.exit()。
  3. 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_smbus 45/45 通过)。

维护者:修改 test.lua 请同步本文件(§2 铁律 + §7.2 CI 约束)。新 CI 异常请在 §7.2 追加并关联 temp/CI-ut.txt / temp/CI-build.txt 行号。