补充测试与规范提交说明

测试是代理最可靠的"自动验收门"，规范的提交则让改动可审查、可回溯。本节讲如何引导代理补齐测试、选择验证信号，以及提交前的检查清单与提交说明写法。

一、为什么要主动要求补测试

• 测试把"是否完成"变成可执行的通过/失败信号，代理可据此自我迭代，减少人工反复核对。
• 测试锁定当前正确行为，为后续重构（第 6 章）提供安全网。
• 回归测试能防止同类 Bug 再次出现，尤其适合边界条件与历史缺陷。

二、引导补测试的方法

1. 先让代理盘点现有测试结构与命名风格，新测试跟随项目既有约定，不另起一套风格。
2. 明确覆盖范围：正常主路径、边界值、非法输入与错误分支；不必追求一次性覆盖所有边角，先覆盖关键路径。
3. 对缺陷修复，先写复现失败的回归用例，再让修复使其转绿。
4. 让代理运行测试并根据失败信息迭代，直到相关用例全部通过；必要时补充类型检查与构建验证。

验证类型	回答的问题	是否可自动运行
单元测试	函数/模块逻辑是否正确	是
集成测试	模块协作与外部依赖是否正常	通常是
构建/类型检查	整体能否编译、类型是否一致	是
Lint/静态检查	风格与常见问题是否合规	是
UI/交互验收	界面与用户体验是否符合预期	通常需人工或截图对比

三、提交前检查清单

• 相关测试、构建、静态检查均通过，并保留可说明结果的输出。
• 用只读命令核对改动范围，确认没有夹带无关文件、调试代码、注释掉的实验逻辑。
• 确认代码与配置中不包含密钥、令牌、个人路径等敏感信息。
• 错误处理、空值与边界输入已覆盖；外部可见文案与提示保持一致。
• 涉及接口、配置、数据结构变化时，确认兼容性与必要的文档/迁移说明。

四、规范提交说明

• 标题一行概括"做了什么"（动作 + 对象）；正文说明"为什么这样做"、关键取舍与影响范围。
• 关联需求或缺陷编号，便于回溯；说明破坏性变化与需要人工配合的操作。
• 可把固定的提交前检查与提交说明结构沉淀为项目自定义命令（呼应第 7 章），保证团队提交风格一致。

五、测试覆盖的优先级与命名约定

• 先主路径后边角：优先覆盖核心成功路径与历史上出过 Bug 的边界，再逐步补全异常分支；不为追求覆盖率数字补无断言的空壳用例。
• 跟随既有风格：测试文件位置、命名、夹具与断言写法与项目现有用例保持一致，降低阅读与维护成本。
• 一个用例验证一个行为：断言聚焦可判定的输入—输出与副作用，避免一个用例堆砌多个互不相关的断言导致失败原因不清。
• 缺陷用例先红后绿：回归用例必须先在修复前失败、修复后通过，才能证明它真的锁住了该缺陷。

六、提交说明结构化模板（人工定稿）

提交草稿由代理辅助生成，最终由人确认。推荐结构如下，方括号按实际填写：

部分	写什么
标题（一行）	动作 + 对象，概括本次唯一目的，如"修复校验缺失导致的空值崩溃"。
背景/原因	为什么要改：现象、根因或需求来源；关联缺陷/需求编号。
改动要点	分条说明关键修改与取舍，不列逐行 diff。
验证方式	执行的测试/构建命令与结果；UI 类改动补充人工核对结论。
影响与回退	兼容性影响、是否需要配置/数据变更、出现问题如何回退。

七、FAQ

问题	处理建议
项目缺少测试，不敢让代理直接改	先为目标模块补最小特征测试锁定当前行为，再让代理在安全网内修改；无测试的大改动先拆小、分步验证。
测试很多但跑起来很慢	先跑与改动相关的定向测试快速反馈，收尾再跑全量；不要用"全量还没跑"掩盖定向失败。
代理生成的测试只断言不关键的结果	要求断言核心输出、错误分支与关键副作用；剔除无验证力的形式化用例。
一次提交混了多个功能点	拆成聚焦单一目的的多个提交；每个提交都应可独立构建、可独立回退。
提交前发现疑似密钥/个人路径	先清除再提交；凭据与本地路径不进入版本库（呼应第 14 章安全排查）。

八、动手练习

• 练习 1：为一个既有函数补 3 个用例（正常、边界、非法输入），命名跟随项目风格，并让其中非法输入用例先暴露一个缺失校验。
• 练习 2：把一次真实改动按六节模板整理提交说明，删除逐行 diff 描述，只保留原因、要点、验证与回退。