sub2api-cn-relay-manager/docs/2026-05-30-TESTING_QUALITY_UPGRADE.md

2026-05-30 测试能力与质量保障增强

背景

当前仓库虽然已经有：

• 单元测试
• SQLite 集成测试
• portal 资产检查
• real-host 验收脚本

但在测试治理上仍有两个明显短板：

1. 缺统一入口

   • 质量门禁主要依赖开发者手动记忆若干命令
   • 缺少“一键执行 + 汇总结果 + 显式门槛”的脚本化入口

2. 缺覆盖率管理

   • 覆盖率门槛写在 AGENTS.md
   • 但没有配置文件和脚本把门槛真正执行出来
   • 低覆盖包不够显性，容易在后续迭代中悄悄回落

本次增强

1. 新增统一质量门禁脚本

• scripts/test/verify_quality_gates.sh

职责：

• 统一执行：
  • gofmt -l .
  • go vet ./...
  • go test -cover ./internal/...
  • go test ./tests/integration/... -count=1
• 生成 coverage gate 报告
• 对低覆盖包给出显式 warn
• 对 core 包低于门槛时直接 fail

2. 新增覆盖率阈值配置

• tests/quality/coverage_thresholds.tsv

当前策略分两层：

• core
  • 当前必须硬门槛通过
  • 先覆盖最关键业务包：
    • internal/access
    • internal/pack
    • internal/provision
• watch
  • 先做显式非回归治理
  • 对已有低覆盖或大体量包给出可见阈值，避免继续恶化

3. 补充脚本自检

• scripts/test/test_real_host_scripts.sh 新增了对 verify_quality_gates.sh 和阈值配置文件的静态回归

4. 提升低覆盖工具包测试

• internal/overlay/executor_test.go

新增覆盖：

• nested output dir 拒绝
• missing patch 错误路径
• metadata 写入内容
• copyTree 对 .git 过滤
• symlink 保留

建议执行方式

后续每次提交前，优先跑：

bash ./scripts/test/verify_quality_gates.sh

如果本次还改了 portal 资产或 real-host 支撑脚本，再补：

bash ./scripts/test/test_tksea_portal_assets.sh
bash ./scripts/test/test_real_host_scripts.sh

后续建议

下一阶段如果继续增强测试能力，优先做这三件事：

1. 给 internal/app 增加不依赖本地监听端口的 handler 级测试，先把 coverage 稳定抬过 70%
2. 把 watch 包分批提升为 core
3. 给 verify_quality_gates.sh 增加机器可读输出，例如 JSON 汇总，方便未来接 CI 或日报