9.0 KiB
测试规范（Dungeon Sweeper）
约束范围：
game/smoke/、game/tests/与一切场景探针的编写与验收。 分工：测试执行许可（什么时候允许跑测试）归 CLAUDE.md「硬性红线·测试执行两入口铁规」；跑什么闸、什么顺序归tools/run_all_gates.sh（脚本即清单，本文与 CLAUDE.md 均不另列）；本文管测试怎么写、怎么算合格。
写任何测试前必须通读本文。
1. 测试总纲——"存在"必须证明"可达且正确"
核心层验收标准通过不算有测试：GDScript 编译不查字典字段与时序，呈现层错误只在运行时暴露。 测试必须证明功能可达（用户真的能用到）且行为正确（结果符合验收标准）。
2. 场景级探针标配
每新增一个可交互 UI 区域（视图/覆盖层/面板），必须配套场景级 headless 探针： 真实实例化场景 → 驱动真实输入路径 → 断言可见性与状态。
凡模态覆盖层，探针必须断言：打开后自身 visible 且遮挡物已隐藏（模态被遮挡 = 功能存在但不可达）。
3. 缺陷修复必须沉淀回归断言
每个缺陷修复必须在探针或冒烟中留下能抓住该缺陷的断言（例：旗动作耗尽 AP → 必须进入第 2 轮； 选用道具 → 库存态必须变 Used）。没有回归断言的修复视为未完成。
4. 提交前全量验证
交付前跑 tools/run_all_gates.sh（不带 --quick）全绿——该脚本是全部验证闸的唯一入口与唯一清单，本文禁另列闸件清单。闸件增减只改脚本。
行为探针使用随机化玩家行为（旗/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。
5. 测试函数怎么写——验收清单条目的落码规范
需求卡片 §7「逐需求点验收清单」每一条都要落成可执行的验证；本文定统一写法，卡里定每批的具体内容（测什么/注入哪里）。写卡期查不出执行载体的条目=不可测，当场呈报，禁拖到实现期。
-
执行载体五选一，逐条声明：单元测试（
tests/run_all）／冒烟断言（smoke_all.gd对应场景段）／场景探针（smoke/下*_probe）／MC 同种子逐项比对／人工核对（仅限无法自动化的纪律类需求点，如命名锁定、数值占位）。行为类条目以自动化载体为主。 -
粒度与对应关系：每条清单条目至少一个自动断言；多条条目可合用一个测试函数。断言失败消息末尾带编号尾缀〔卡短名 Vn〕（如〔秘宝批 V3〕）——断言与卡片清单可互相 grep 查找。
-
断言词汇按验证对象五选一：
词汇 适用场景 逐位相等 同种子下确定性公式与结算的精确逐项比对 区间/差值带 概率与平衡读数（MC 同种子配对比较，出带即红） 快照比对 存档域结构、配置表行结构 重放 同种子断点回放、改前改后配对 状态/计数器断言 条件解锁、限次、充能——置数据→走路径→断计数值 -
调试注入两层（能力测试与流程体验两分法的落码面）：自动化测试=测试代码直调核心层写口构造状态（直改数据表行/计数器/存档域，不经 UI、不走正常资源积累流程——冒烟现役做法）；人工体验=DebugOverlay/DS_DEBUG 调试面，服务用户目检。清单条目的「怎么测」必须写到数据面粒度：改哪张表哪行、置哪个计数、调哪个核心写口。
-
换代批旧验证约束同生死：删除旧数据行/旧实现代码的批次，必须同批摘除只验证旧实现的断言与护栏校验，由新断言替代——旧件断言残留=冒烟假绿来源；合并后冒烟全绿且全仓无旧件残留引用为证。
6. 变异验证——验收函数的拦截能力自证
测试绿只证明「当前代码没犯这个错」，不证明「犯了这个错会被抓住」。新增或改写的验收函数（冒烟断言／探针自检／闸机判据）必须配一次变异验证，把拦截能力自证一遍。无变异红记录的断言不写「已验收」，只写「已实现，拦截能力未证」。
操作四步（逐条落实现报告变异验证记录表）：
- 注入——把被测件改坏成该类缺陷的最小形态（翻装配序、注释一行
add_child、把状态源取反、把层visible置 false）。一次只注入一处；可直接改源码，不必留长期开关。 - 跑最窄的那一道闸——只跑能覆盖该断言的最小单元（单冒烟脚本／单探针／单比对命令），禁跑全套闸（见 process-conventions §6 闸机轮次纪律）。判据：注入后该断言必须变红；红在别处而目标断言仍绿＝判据没打在缺陷上，按第 4 条处理。
- 精确还原——
git checkout -- <文件>（不用git stash、不手工回改，防残留）。还原后复跑同一道闸确认回绿，才算本轮闭环。 - 记录——变异点（文件:行）、跑的闸、红输出摘要、还原结论，逐条进实现报告记录表。
变异不红怎么办（二选一，不许含糊带过）：
- 改判据——把断言打到真正的缺陷面上（例：断言「菜单标题可见」只查截图墨色占比时，把菜单层藏起来仍不红——底层棋盘透过标题框照样给出高反差像素；改查
is_visible_in_tree或加 golden 逐像素比对才红）。 - 如实标注拦截边界——判据本身只覆盖弱面的（如「只证伪整框空白／整框糊，不证明框里是何内容」），在断言注释与报告里写明边界，并说明强判据由哪一件承担。
判据强弱分层：同一缺陷面往往需要多件配合——可见性／状态源类缺陷由 is_visible_in_tree、树序、状态源取值的运行期断言抓；内容／观感类缺陷由 golden 逐像素比对抓；占比／统计类判据（墨色占比、纹理幅度）只能兜「整框空白／整框糊／压 busy 纹理」，是补充不是主力。写卡时按此分层配齐，别指望一条断言包打。
7. 判定三硬闸——闸承载的构造义务（迭代 29 三硬闸 2026-10-17 用户裁升格为纪律）
任何新增或改写的闸承载（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归架构文档「测试与质量域」节（本文不另列闸件清单）：
- 退出码为唯一权威判据——输出里的 PASS 串只作附加判据不作判据主体；打印 PASS 后
quit(1)必须判红。 - SCRIPT ERROR / Parse Error 扫描面在位——GDScript 脚本错误不改进程退出码、不计失败数（机制事实见 §8），错误标记必须扫输出，且判据必须覆盖「跑了但半途脚本错误」态——退出码 0 但输出缺预期签名同样判红（防静默退出）。
- 断言数下限——零断言的正常返回与断言失败必须区分开（现行做法：
Kit.finish零断言返回专用退出码 2，不与「断言失败=1」混用，否则致命类套件的期望码协议会放过空跑）。- 负面套件（测试目标就是产生错误输出）仅可豁免第 2 闸，且须在 manifest 显式标记，其余两闸照判。
- 子进程输出须经系统命令解释器重定向落盘再读——
OS.execute的输出管道在本机恒空。
新写测试件全类型标注（2026-10-17 用户裁写法纪律）——新写的测试件（冒烟断言／探针／单测）参数、返回值、容器一律带类型标注，与 S9 对产品码的要求同型；存量不强制清扫，被批次触碰时顺带换代。暂不机器闸（S9 扫描面=产品码，smoke/tests 豁免是测量面直构惯例的既有裁量）。
8. 判定可靠性优先于覆盖率（迭代 29 核心命题 2026-10-17 用户裁成节）
- 「跑一遍没崩＝通过」无效：测试绿只证明当前代码没犯这个错，不证明犯了这个错会被抓住；断言存在不等于断言执行。
- 脚本错误会静默中断所在函数的剩余断言，而套件仍报全绿（机制事实）：GDScript 无脚本错误陷阱 API，错误不改进程退出码、不计失败数。三处实证：①2026-09-19「309 项 0 失败」实为断言未跑全（状态记录 83）；②敌人表行集纪律 10 条断言因定型数组赋值错误从未执行（迭代 29 修复后两条正向见红＝夹具本缺锚行）；③
Callable形参类型写错致解析函数返回 null、后续断言整段蒸发。 - 由此产生两条义务：写闸件按 §7 配三硬闸；写验收函数必须自证断言全数执行——变异验证（§6）为主证，反例实证（构造缺陷态改前判绿／改后判红）与零命中自检（扫描面为空即判红）为辅证。
- 覆盖率不是目标：行覆盖率度量缺失（Godot 无内建，第三方属新基建，是否引入 06 在册待裁）；现行补洞=零指名单测清单+人工判定，判定可靠性靠上列自证手段，不靠覆盖率数字。