DKChan
1d4ac91e3b
用户令「迭代完成前必须全量跑一遍所有测试」。起因是 iter27 台账只记 probe --click 未记 --full，t17_defer_probe 红了整个迭代无人发现——根因是闸清单散落 CLAUDE.md / process-conventions.md / test-conventions.md 三处、彼此不一致、且无任何机器校验。 - tools/run_all_gates.sh（新）：全部验证闸的唯一入口与唯一清单，串跑冒烟/单元/探针 --click/--full/渲染/doc 三闸/静态扫描/熵增闸共十道，写回执 game/tests/.gates/receipt.json。 与 baseline.json 比对判定：基线红且红项清单未变＝存量红零新增（不判失败）， 基线绿转红或红项清单变化＝新增红（判红）。python 解释器自动解析带 PIL 的解释器 并前置 PATH（渲染闸三个脚本依赖 PIL，用错解释器会假红）。 - .zcode/hooks/worktree-guard.sh：Bash 分支加合回闸——merge/rebase/cherry-pick 进 master 前按目标分支反查 worktree 回执，校验 commit 匹配/非 quick/无新增红三态， 任一不满足 exit 2 拦截（九态实测：匹配放行、commit 错/quick/含红/无回执/rebase 全拦）。 - game/smoke/t17_defer_probe.gd：隔离面从 main.save_manager = iso_c 改 ProbeUiUtil.isolate_save（iter27 已确立口径）。原写法对 getter-only 属性赋值无效 ——组合根 save_manager/meta 是 autoload 读视图，隔离必须落在单例上。修复后 --full 转绿。 - doc_link 三处死链归零：数据配置.md 已退役探针指路、元进度.md/天赋树.md 已改名文档链接。 - CLAUDE.md / process-conventions.md §3第10条 / test-conventions.md §4 三处 「交付前跑什么」统一为一句话＝跑 run_all_gates.sh，删散落清单。 闸况：冒烟 0 / 单元 0 / --click 0 / --full 0 / 渲染 0 / doc_link 0 / doc_term 0 / 熵增 0；gdd_lint 与 static_scan 为存量红，已落 baseline.json 待判读清偿。
68 lines
6.1 KiB
Markdown
68 lines
6.1 KiB
Markdown
# 测试规范（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「逐需求点验收清单」每一条都要落成可执行的验证；本文定统一写法，卡里定每批的具体内容（测什么/注入哪里）。写卡期查不出执行载体的条目=不可测，当场呈报，禁拖到实现期。
|
||
|
||
1. **执行载体五选一，逐条声明**：单元测试（`tests/run_all`）／冒烟断言（`smoke_all.gd` 对应场景段）／场景探针（`smoke/` 下 `*_probe`）／MC 同种子对拍／人工核对（仅限无法自动化的纪律类需求点，如命名锁定、数值占位）。行为类条目以自动化载体为主。
|
||
2. **粒度与对应关系**：每条清单条目至少一个自动断言；多条条目可合用一个测试函数。断言失败消息末尾带编号尾缀〔卡短名 Vn〕（如〔秘宝批 V3〕）——断言与卡片清单可互相 grep 查找。
|
||
3. **断言词汇按验证对象五选一**：
|
||
|
||
| 词汇 | 适用场景 |
|
||
|---|---|
|
||
| 逐位相等 | 同种子下确定性公式与结算的精确对拍 |
|
||
| 区间/差值带 | 概率与平衡读数（MC 同种子配对比较，出带即红） |
|
||
| 快照比对 | 存档域结构、配置表行结构 |
|
||
| 重放 | 同种子断点回放、改前改后配对 |
|
||
| 状态/计数器断言 | 条件解锁、限次、充能——置数据→走路径→断计数值 |
|
||
|
||
4. **调试注入两层（能力测试与流程体验两分法的落码面）**：自动化测试=测试代码直调核心层写口构造状态（直改数据表行/计数器/存档域，不经 UI、不走正常资源积累流程——冒烟现役做法）；人工体验=DebugOverlay/DS_DEBUG 调试面，服务用户目检。清单条目的「怎么测」必须写到数据面粒度：改哪张表哪行、置哪个计数、调哪个核心写口。
|
||
5. **换代批旧验证约束同生死**：删除旧数据行/旧实现代码的批次，必须同批摘除只验证旧实现的断言与护栏校验，由新断言替代——旧件断言残留=冒烟假绿来源；合并后冒烟全绿且全仓无旧件残留引用为证。
|
||
|
||
## 6. 变异验证——验收函数的拦截能力自证
|
||
|
||
测试绿只证明「当前代码没犯这个错」，不证明「犯了这个错会被抓住」。新增或改写的验收函数（冒烟断言／探针自检／闸机判据）必须配一次变异验证，把拦截能力自证一遍。**无变异红记录的断言不写「已验收」，只写「已实现，拦截能力未证」。**
|
||
|
||
**操作四步（逐条落实现报告变异验证记录表）**：
|
||
|
||
1. **注入**——把被测件改坏成该类缺陷的最小形态（翻装配序、注释一行 `add_child`、把状态源取反、把层 `visible` 置 false）。一次只注入一处；可直接改源码，不必留长期开关。
|
||
2. **跑最窄的那一道闸**——只跑能覆盖该断言的最小单元（单冒烟脚本／单探针／单比对命令），禁跑全套闸（见 process-conventions §6 闸机轮次纪律）。判据：注入后该断言**必须变红**；红在别处而目标断言仍绿＝判据没打在缺陷上，按第 4 条处理。
|
||
3. **精确还原**——`git checkout -- <文件>`（不用 `git stash`、不手工回改，防残留）。还原后复跑同一道闸确认回绿，才算本轮闭环。
|
||
4. **记录**——变异点（文件:行）、跑的闸、红输出摘要、还原结论，逐条进实现报告记录表。
|
||
|
||
**变异不红怎么办（二选一，不许含糊带过）**：
|
||
|
||
- **改判据**——把断言打到真正的缺陷面上（例：断言「菜单标题可见」只查截图墨色占比时，把菜单层藏起来仍不红——底层棋盘透过标题框照样给出高反差像素；改查 `is_visible_in_tree` 或加 golden 逐像素比对才红）。
|
||
- **如实标注拦截边界**——判据本身只覆盖弱面的（如「只证伪整框空白／整框糊，不证明框里是何内容」），在断言注释与报告里写明边界，并说明强判据由哪一件承担。
|
||
|
||
**判据强弱分层**：同一缺陷面往往需要多件配合——**可见性／状态源类**缺陷由 `is_visible_in_tree`、树序、状态源取值的**运行期断言**抓；**内容／观感类**缺陷由 **golden 逐像素比对**抓；**占比／统计类**判据（墨色占比、纹理幅度）只能兜「整框空白／整框糊／压 busy 纹理」，是补充不是主力。写卡时按此分层配齐，别指望一条断言包打。
|