gbrain 重型测试体系指南:tests/heavy 目录的定位、运行机制与工程实践
gbrain 重型测试体系指南:tests/heavy 目录的定位、运行机制与工程实践
导读
tests/heavy/ 是 gbrain 项目中针对运维形态(ops-shape)问题设计的一层端到端测试体系:它用 shell 脚本驱动真实基础设施(Postgres、大型 fixtures、多进程并发)对 gbrain 进行整体性验证,单次运行耗时以分钟计,因此被刻意排除在默认的 bun test 之外。本文将以 tests/heavy/README.md 为骨架,结合该目录下各脚本与 scripts/run-heavy.sh、_db_floor.sh 等源码实现,系统讲解这层测试的适用场景、运行方式、数据库安全护栏、命名规范、CI 调度与编写风格,帮助你判断"什么该进 tests/heavy、什么该进 *.slow.test.ts",并具备独立编写、运行和排查重型测试的能力。
一、为什么需要独立的重型测试层:与 *.slow.test.ts 的分工
gbrain 的测试体系是分层设计的,tests/heavy/ 与 test/ 目录下的 *.slow.test.ts 有意共存(coexist intentionally),两者解决的是不同形态的问题。
| 维度 | tests/heavy/ 下的 shell 脚本 |
test/*.slow.test.ts |
|---|---|---|
| 运行载体 | bash 脚本,脱离 bun 测试运行器 | TypeScript,使用 bun:test 导入 |
| 验证形态 | ops-shape:真实基础设施上的整体行为 | correctness-shape:单个函数的行为断言 |
| 依赖控制 | 需要真实 Postgres、大 fixture、多进程 | 可以 stub 外部依赖 |
| 单次成本 | 大于 ~30s 墙钟时间 | 相对更快 |
| 触发方式 | bun run test:heavy |
bun run test:slow(见 package.json 中 test:slow 脚本定义) |
依据 tests/heavy/README.md,需要放进该目录的测试具备以下特征之一:
- 单次运行墙钟时间超过约 30 秒;
- 需要真实 Postgres(而非内存态 PGLite);
- 需要拉起多个进程或度量并发行为;
- 需要度量系统指标(RSS、负载下延迟、锁竞争);
- 需要针对已提交的历史数据库形态测试升级/迁移矩阵。
而 *.slow.test.ts 的准则是:能放进 bun test(TypeScript、bun:test 导入)、属于"正确性形态"(断言单个函数行为)、且可以 stub 外部依赖。
二、如何运行:runner、单脚本直跑与包管理入口
2.1 全量顺序执行
tests/heavy/ 的 runner 是 scripts/run-heavy.sh,它发现本目录顶层(非递归)的所有 tests/heavy/*.sh 文件,按**字典序(lexical order)**顺序执行,遇到第一个非零退出即中止。两种等价调用方式:
# 方式一:通过 package.json 脚本(推荐)
bun run test:heavy
# 方式二:直接执行 runner
bash scripts/run-heavy.sh
runner 还支持按 glob 过滤单跑:
# 只跑文件名匹配 sync_* 的脚本(空参数则全部)
bash scripts/run-heavy.sh 'sync_*'
2.2 单个脚本直跑
每个重型脚本都被设计为可独立直接执行(这也是数据库安全护栏必须由脚本自己再 source 一次的原因):
tests/heavy/<script>.sh
2.3 runner 的退出码语义
从 scripts/run-heavy.sh 的源码看,退出码约定为:
0:全部脚本通过(或未发现任何脚本——属于信息性返回);N:第一个失败脚本的退出码(runner 会打印FAIL ($f exited $rc after ${elapsed}s)并中断后续脚本)。
2.4 典型运行前准备(真实 Postgres 场景)
多数据库相关脚本在未设置 DATABASE_URL 时会给出 Docker 启动提示并以信息性状态跳过,例如:
docker run -d --name gbrain-test-pg \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=gbrain_test -p 5434:5432 pgvector/pgvector:pg16
export DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test
注意数据库名使用 gbrain_test——这正好满足下文数据库安全护栏对"test"词段的要求。
三、数据库安全护栏:_db_floor.sh 的 test 名称下限(issue #3485)
重型脚本会执行破坏性操作(schema 删除、迁移重放、并行 sync),作用于环境变量指定的任意数据库 URL。为防误伤真实数据库,tests/heavy/README.md 要求 runner 与每个触碰数据库的脚本都 source 共享的 _db_floor.sh。
3.1 双重 source 的原因
- runner 在 scripts/run-heavy.sh 顶部一次性 source
tests/heavy/_db_floor.sh,覆盖整条 lane; - 但脚本被文档化为可直接单跑,因此每个触碰数据库的脚本自己还要再 source 一次(如 pg_upgrade_matrix.sh、sync_lock_regression.sh、frontmatter_scan_wallclock.sh、_build_legacy_fixtures.sh),仅靠 runner 层不够。
3.2 判定规则
依据 _db_floor.sh 的实现,护栏同时检查 两个变量——DATABASE_URL 与 GBRAIN_DATABASE_URL,因为重型脚本会 shell out 到真实 CLI(gbrain doctor / gbrain sync),而 src/core/config.ts 中 GBRAIN_DATABASE_URL 的解析优先级高于 DATABASE_URL,只检查其中一个会让另一个直通真实 brain。规则为:
- 数据库名必须包含 "test" 作为独立词段(通过
(^|[_-])test([_-]|$)匹配,例如gbrain_test); - 或者精确名称通过一次性环境变量
GBRAIN_E2E_ALLOW_DB=<name>显式放行(推荐一次性内联使用,如GBRAIN_E2E_ALLOW_DB=name ./script,而非写入 shell profile 永久解除护栏); - 查询字符串会在提取名称之前被剥离(
?host=/tmp/test-sockets这类形式不能把 test 词段偷渡过去,数据库名取的是去 query 后 URL 的最后一个路径段); - 不符合上述任一条件则打印 REFUSING 并以退出码 2 拒绝执行。
3.3 PGLite 脚本的特例
基于 PGLite 的脚本(measure_rss.sh、read_latency_under_sync.sh、sync_timeout_rescue.sh)不触碰真实数据库,改为直接 unset DATABASE_URL(必要时连同 GBRAIN_DATABASE_URL),在内存态引擎内完成测量。
四、命名规范:顶层脚本、下划线 helper 与 fixtures
tests/heavy/README.md 对目录内容规定了三条命名约定,runner 的实现也与之严格对应:
| 形态 | 命名 | 说明 |
|---|---|---|
| 顶层测试脚本 | tests/heavy/<name>.sh |
被 runner 拾取(runner 用 find tests/heavy -maxdepth 1 -type f -name '*.sh' 发现,非递归) |
| 库/helper | tests/heavy/_<name>.sh |
前导下划线让 runner 跳过(case _*) continue);用于 fixture 构建、共享 setup、需要必选参数或不可独立运行的内容 |
| 输入数据 | tests/heavy/fixtures/<name> |
提交入库的 SQL、JSON 等输入数据 |
当前仓库中的实际例子:_build_legacy_fixtures.sh、_db_floor.sh、_measure_rss_workload.ts、_read_latency_workload.ts、_sync_timeout_rescue_workload.ts 均为下划线 helper;fixtures/ 下是 down-mutate-pre-v0.13.sql 与 down-mutate-pre-v0.18.sql 两个历史形态 SQL。
五、CI 调度:夜间运行与按需标签
- 重型测试通过
.github/workflows/heavy-tests.yml每天 UTC 08:17 夜间运行; - 带
heavy-tests标签的 PR 也会触发; - 它们不参与默认 PR CI 矩阵——那条 gate 必须保持快速。
六、失败输出约定:审计日志与 CI 制品
每个重型脚本会把当次运行日志写入 ~/.gbrain/audit/heavy-<script>-<ts>.log(尊重 $GBRAIN_HOME 覆盖,即 ${GBRAIN_HOME:-$HOME/.gbrain}/audit),内容包含子进程的 stdout/stderr、环境状态与捕获的度量指标。CI 工作流在失败时将这些日志作为 artifacts 上传,便于无需本地复跑即可定位问题(例如 sync_lock_regression.sh 会用 trap 把日志复制到 /tmp/heavy-sync_lock_regression-<ts>.log 以在临时 GBRAIN_HOME 被清理后仍可查看)。
七、源码级纵深:五个重型脚本各自验证什么
以下脚本当前都存在于 tests/heavy/,逐一说明其验证目标,便于理解重型测试的实战价值。
7.1 measure_rss.sh——RSS 预算门禁
验证目标:构建合成 brain、跑读负载、测峰值 RSS,并与已提交基线 tests/heavy/rss-baseline.json 比较。关键参数:
BRAIN_PAGES(默认 200):合成 brain 的页数。更大的值更贴近真实,但 PGLite 插入 + autolink 在 Darwin 上超过约 300 页呈超线性增长(实测 200 页约 1.2s,500+ 页会命中 300s 超时);NUM_QUERIES(默认 50):搜索查询次数;RSS_THRESHOLD_PCT(默认 25):回归阈值百分比;STRICT_RSS(默认 0):置 1 时超标即失败,否则仅信息性报告。
基线刷新被严格限定在 Linux:macOS 测量走 process.memoryUsage().rss(VmRSS)回退路径,而 gbrain 生产环境刻意回避该指标;提交 macOS 来源的基线会锁死错误指标并产生虚假的 CI delta_pct。刷新命令为 tests/heavy/measure_rss.sh --refresh-baseline(非 Linux 直接拒绝,退出码 2),且要求工作负载报告的 measurement_path 为 proc(即来自 /proc/self/status)。当前 rss-baseline.json 是空桩,peak_rss_kb 待首次 Linux CI 运行填充,因此在此之前每次测量都只是信息性输出。
7.2 read_latency_under_sync.sh——同步负载下的读延迟
验证目标:三次独立的内存 PGLite 空闲/负载对比。其公共写入、零被忽略错误、真实在途重叠度 ≥90% 是始终强制的;STRICT_LATENCY=1 时额外强制执行中位数三次 p99 回归预算。默认参数:BRAIN_PAGES=500、NUM_QUERIES=200、NUM_WRITERS=4、WRITES_PER_WRITER=25、THRESHOLD_PCT=50。它实际调用 scripts/persistence/performance.ts(--engine=pglite),并把度量结果写入 manifest JSON,输出空闲 p99、负载 p99、delta_p99_pct、重叠度与判定结论。
7.3 sync_timeout_rescue.sh——同步超时自愈回归
验证目标:以较小规模复现 PR #1472 RFC 中"8/12 个 cron 任务在 1803s 超时"的场景,并断言 v0.41.13.0 的 v4 修复打破了级联。背景是生产故障模式:4 个联邦源 × 37 万页、每小时 cron 只有 30 分钟墙钟、sync --all 是单异步扇出进程、cron SIGKILL 会连带杀死尚未到达的源并泄漏中途导入源的 per-source 锁。该脚本用 4 个内存 PGLite "源"(由小型 git fixture 支撑)+ 3 轮连续 sync 波(--timeout 收紧到每源至少命中一次部分路径)验证:
--timeout让每个源按各自预算优雅自终止(runOne内基于 AbortController 的 per-source budget);--break-lock --all --max-age 1800通过新的last_refreshed_at语义跨源 cron 自愈;- 部分状态保留
last_commit,下一轮 cron 重走相同 diff,content_hash短路已导入文件。
断言条件:3 轮波内每个源都达到 last_commit === HEAD。可调参数 PAGES(默认 200)、WAVES(默认 3)、TIMEOUT_SECONDS(默认 5)、STRICT(默认 1)。脚本注释明确说明它不是 Postgres 测试(PGLite 内部强制串行 sync),Postgres 并行扇出场景在 test/e2e/sync-parallel.test.ts 中覆盖。
7.4 sync_lock_regression.sh——并发 writer 锁竞争回归
验证目标:对同一数据库拉起 N 个并发 gbrain sync 进程,断言三条契约:
- 恰好一个进程赢得 writer 锁(
gbrain_cycle_locks表中的gbrain-sync行); - 其余 N-1 个以 "Another sync is in progress" 快速失败(不排队等待)——对应 src/commands/sync.ts 中
performSync使用tryAcquireDbLock无等待获取(脚本注释指向 sync.ts:377); - 全部进程退出后
gbrain_cycle_locks中零泄漏。
该脚本注释记录了工程教训:最初计划断言的语义是错的("N-1 等待然后逐一完成")且快照了错误的表(pg_locks 而非 gbrain_cycle_locks),两个 reviewer 都指出了问题——重型测试必须验证真实契约。脚本会把 GBRAIN_HOME 隔离到临时目录(防止写入 sync.repo_path 弄脏开发者真实配置),用 psql 把默认 source 的 local_path 指向临时 brain 目录,并注意 --repo 是 sync 的规范 brain-dir 标志(旧的 --dir 会被静默忽略),--no-embed 用于 CI 无 embedding 密钥的环境。可用参数 NUM_PARALLEL(默认 4)。判定为 1 个 winner + N-1 个 lock-busy loser + 0 泄漏,否则失败。
7.5 frontmatter_scan_wallclock.sh——doctor frontmatter 扫描墙钟冒烟
验证目标:复现 v0.38.2.0 生产修复前的负载场景——一个含 N 个真实 markdown 页(位于常规子目录)外加 M 个 node_modules/ 下 dummy 页的 brain。修复前 walker 会下探 node_modules 并对每个条目 stat,N+M≈60K 时扫描会超过 doctor 默认 30s 预算。脚本断言修复后:
gbrain doctor退出码为 0 或 1(允许 warn),绝不能被 timeout 杀死;frontmatter_integrity状态为ok(干净前缀、无 partial),而非warn;- 总墙钟低于
WALLCLOCK_BUDGET_S(默认 15s)。
为什么是 60K 而不是原报告的 200K:60K 是"下探 node_modules 至少增加 5s 墙钟(现代 SSD 上约 5 万次额外 stat)"的最小规模;200K 需要约 30s 造 fixture,是重型测试与酷刑测试的分界线。脚本注释还记录了一次 plan review 教训:1500 文件预算在修复前后都通过、证明不了任何东西。脚本默认 PGLite(无需 DATABASE_URL),设置 DATABASE_URL 则测试 Postgres SQL 路径;REAL_PAGES(默认 10000)与 NODE_MODULES_PAGES(默认 50000)可调。它还用 bun -e(注意不能用 bun run -e,后者会把 -e 当未知脚本名并以退出码 0 打印 usage,导致 INSERT 静默未执行、doctor 扫零源而"空通过")通过引擎 API 注册 source,并刻意在 doctor 前先 init --pglite --non-interactive --no-embedding(--no-embedding 规避 CI 无 embedding provider 密钥的硬性要求)。
7.6 pg_upgrade_matrix.sh——schema 迁移前进矩阵
验证目标:对每个"历史形态"构建 fixture,运行 gbrain doctor,断言其干净到达 LATEST。之所以重要:CLAUDE.md 记载的 10+ 个前向引用 bug(#239/#243/#266/#357/#366/#374/#375/#378/#395/#396)都是因为新发布往 schema blob 里加了"带索引的列"却缺少对应 bootstrap 探针;从多个遗留形态向前走能先于用户命中该类 bug 的下一个成员。
执行流程(每形态):timeout 180s bash tests/heavy/_build_legacy_fixtures.sh <shape> 构建历史 fixture → timeout 120s bun run src/cli.ts doctor --json 走前向修复 → 解析 JSON 中的 status,接受 ok/warn/warnings,拒绝 fail/failures/failed 或空值。当前形态为 pre-v0.13 与 pre-v0.18。脚本还坦诚了能力边界(2026-05-19 冒烟验证):该矩阵捕获整体系统楔住,而非单层 bootstrap 回归——gbrain 有"bootstrap → SCHEMA_SQL replay → migrations → verifySchema"多层防御,单层回归由 test/schema-bootstrap-coverage.test.ts(静态)与 test/e2e/postgres-bootstrap.test.ts(引擎层)兜底。
7.7 _build_legacy_fixtures.sh 与 down-mutate SQL——确定性历史形态构造
该 helper 用确定性替代方案构建历史形态,而非提交会腐烂的 pg_dump blob(pg_dump 版本噪声、不透明 diff、无记录的再生成)。流程:drop public schema → gbrain doctor --json 把空库带到 LATEST(触发 applyForwardReferenceBootstrap → SCHEMA_SQL → runMigrations)→ 应用 down-mutate SQL 剥离前向引用状态。例如 fixtures/down-mutate-pre-v0.13.sql 会删除 idx_links_source/idx_links_origin 索引、去掉 links.link_source/links.origin_page_id 列并把 config.version 回退到 '10',从而模拟 pre-v0.13 形态(对应 issue #266/#357)。脚本坦诚这是 down-mutation 模拟而非真实历史快照——bootstrap 的契约很窄("给定缺少特定前向引用的 brain,initSchema 产出 LATEST brain"),该脚本恰好精确覆盖此契约。
八、编写风格约定
tests/heavy/README.md 为重型脚本规定了明确的风格基线,仓库脚本(如 scripts/check-jsonb-pattern.sh、scripts/run-slow-tests.sh)作为树内风格参考:
#!/usr/bin/env bash开头;set -euo pipefail;- exec 使用显式数组 argv(不用
eval、不用未加引号的 glob); - 每个主要步骤打印一行
[<script>] <action>日志; - 任何失败路径非零退出,并打印足够的诊断上下文;
- 在相关处尊重
$GBRAIN_HOME/$TMP_ROOT环境覆盖。
从前文各脚本可归纳出三条贯穿性的最佳实践:触碰数据库的脚本必须自己 source _db_floor.sh;日志必须落到 ~/.gbrain/audit/(或 $GBRAIN_HOME 覆盖);测量类脚本默认信息性输出、由 STRICT_* 环境变量决定是否升级为硬失败。
九、在 gbrain 测试体系中的定位与扩展建议
结合 package.json 的脚本定义(test:full 依次串起 verify、单测并行、test:slow、有 DATABASE_URL 时的 e2e),可以清晰看到 gbrain 的分层策略:test/ 单测保证函数正确性,*.slow.test.ts 处理冷路径逐文件正确性,tests/heavy/ 处理不适配 bun 测试运行器的运维形态验证,e2e 则覆盖引擎级集成。重型测试的关键取舍是:用几分钟的墙钟时间换取对真实基础设施整体行为的置信度——它检测的是多进程竞态、系统指标回归、迁移楔住与生产负载下的超时级联这类单元测试永远无法暴露的问题。
如果你计划为 gbrain 贡献新的重型测试,遵循本章全部约定即可:先确认它确实超过 30s 墙钟、需要真实 Postgres、多进程或系统指标(否则请改用 *.slow.test.ts);命名上顶层脚本不带下划线、helper 带下划线、输入数据放 fixtures/;触碰数据库前 source _db_floor.sh 并保证目标库名含 test 词段;按风格基线编写并保持每个主要步骤有日志;最后通过 bun run test:heavy 验证整条 lane 通过。
参考文件索引
- 目录规范总览:tests/heavy/README.md
- 顺序 runner 与退出码实现:scripts/run-heavy.sh
- 数据库名安全护栏:tests/heavy/_db_floor.sh
- RSS 预算门禁:tests/heavy/measure_rss.sh、基线 tests/heavy/rss-baseline.json
- 同步负载读延迟:tests/heavy/read_latency_under_sync.sh、底层负载 scripts/persistence/performance.ts
- 同步超时自愈回归:tests/heavy/sync_timeout_rescue.sh
- 并发 writer 锁回归:tests/heavy/sync_lock_regression.sh
- doctor frontmatter 扫描墙钟:tests/heavy/frontmatter_scan_wallclock.sh
- 迁移前进矩阵:tests/heavy/pg_upgrade_matrix.sh、历史形态构造器 tests/heavy/_build_legacy_fixtures.sh、fixtures/down-mutate-pre-v0.13.sql
- 引擎连接与 schema 路径:配置解析 src/core/config.ts、同步锁获取 src/commands/sync.ts
- 兜底与姊妹测试:test/schema-bootstrap-coverage.test.ts、test/e2e/postgres-bootstrap.test.ts、test/e2e/sync-parallel.test.ts