测试策略¶
CCB 的测试目标是用最小、可复现的证据覆盖风险，而不是让每个 PR 无差别运行
全部平台。命令权威来自 ai/test-matrix.yml、Makefile、CI 和测试源码。
从窄到宽¶
- 运行目标文件的格式、Schema 或静态契约检查。
- 运行最接近行为的单元/回归测试，并使用聚焦 Catch2 filter。
- 运行子系统加载或集成检查，例如 JSON 全量加载。
- 公共契约、平台或发布变化再扩大到矩阵构建。
| 变化 | 必要证据 | 常见扩大条件 |
|---|---|---|
| C++ 实现 | make astyle-check、聚焦 Catch2 |
共享核心、序列化、性能热点 |
| 测试框架/公共头 | make -j2 tests |
编译器或 feature 组合差异 |
| JSON/EOC/MOD | formatter 与 make -j2 json-check |
loader、Schema、跨 MOD 交互 |
| Lua 公共契约 | 声明、覆盖、相关单测 | native registration 或 Platform 契约 变化 |
| Agent/文档元数据 | metadata checker 与 tools/agent 测试 |
生成清单或 CI 路由变化 |
| Android | Gradle unit/build 目标 | Java/native 边界或资源打包 |
Platform v1 契约验收命令¶
按完整 Lua 领域批次完成实现、声明和测试源码，再集中运行以下验收入口。 以下是当前命令，不是本次文档修改重新编译游戏或完成所有 API 语义验证的记录。
# validation: agent-context
python3 tools/agent/check_project_metadata.py
python3 -m unittest discover -s tools/agent -p 'test_*.py'
# validation: lua-contract
python3 tools/lua_api/check_luals_declarations.py
python3 tools/lua_api/check_platform_native_inventory.py
python3 tools/lua_api/check_platform_contract.py
python3 tools/lua_api/check_platform_coverage.py
python3 tools/lua_api/check_cmake_contract.py
python3 -m unittest discover -s tools/lua_api -p 'test_*.py'
写回归测试¶
- 测试名说明可观察行为，而不是实现细节。
- 构造最小 fixture，避免依赖测试执行顺序、当前时间或未固定随机状态。
- 失败时保存 filter、断言上下文、日志和 RNG seed。
- 修复 bug 时先证明测试能捕获原问题，再证明修改后通过。
- 不用扩大 timeout 掩盖死锁、无限循环或性能回退。
如实报告¶
PR 中分开列出 Passed、Failed、Not run。Windows、MSVC、Android 或耗时构建没有 实际运行时必须明确写出，不可以用 Linux 配置成功替代。失败应保留首个根因、 修复和重跑结果；偶发失败应记录 seed 和重现次数。