0 Fork 0

Files

T

DKChan 853bd12baa docs(迭代29 T2): 术语订正与 CI 残留清除（机械面）

README：CI 残留 6 处全清——头注 CI 行改「门禁=本地闸」+无远端无 CI 声明、目录布局「CI 冒烟统一入口」
→「单元套件统一入口」、Running「CI 调用点」→「本地闸 02 闸调用点」、「CI 旁必须配外部超时」
→「本地闸必须配」、Static Scan「提交前双跑：本地+CI」→「提交前本地跑」、「## CI」整节（含 gdUnit4
安装说明）→ 改写为「## 本地闸（唯一验收门禁）」。
run_all.gd 头注 CI 残留 2 处清除（外部超时改本地闸、探针由 probe_gate.sh 调用）。
CLAUDE.md 单件直跑清单里 run_smoke.py 标注为「系统级断言面」并指路术语表。

术语：新增 README「术语（本项目内的唯一语义）」小节——冒烟=秒级存活检查／单元套件／场景探针／
集成用例四词各归其位，并显式点破两处历史遗留命名（run_smoke.py 与 game/smoke/ 名带 smoke，
实际承载的是系统级断言面与场景探针，判定看语义不看文件名）。「逻辑冒烟」全库清零。
README 套件计数按开工日读数订正为 26（example_test 退出生产 manifest）。

2026-10-16 15:11:17 +08:00

7.5 KiB

Raw Blame History

Test Infrastructure — Dungeon Sweeper

Engine: Godot 4.7.2-stable（GDScript 单语言） Test Framework: 双载体——--headless --script 单元套件 + headless 场景探针；gdUnit4 deferred（D2 OQ1 关闭形态——本仓库不引第三方测试框架，需求见下「门禁」节）门禁: 本地闸——tools/run_all_gates.sh（全量，收口唯一验收入口）/--quick（中段自检）。本仓库无远端、无 CI（.github/workflows/ 已删除，不建不留不参考）；闸清单只在本脚本定义，文档不另列 Setup date: 2026-09-12（2026-09-27 7f24b640 三层收敛：根 tests/ 并入 game/tests/、docs 并入 design/dev/、production 解散） 参考实现: game/smoke/（冒烟断言 + 场景探针族——正式工程的活样板；断言计数双口径见下节）

Directory Layout

tests/
  unit/           # 隔离单元测试（公式/状态机/纯逻辑）——extends SceneTree + quit(code)
  smoke/          # critical-paths.md——人工 gate 清单（/smoke-check 读取）
  evidence/       # 截图与人工签核记录
  run_all.gd      # 单元套件统一入口（套件 manifest 协议，D2 AC-2b）
  static_scan.sh  # 静态扫描域 S1–S8 可执行子集

integration/ 目录已删空壳（迭代 19 卡① T4/Q8 2026-10-08——彼时仅有章程 README 无实体）。章程句保留在此：将来跨系统测试（Core-Core 集成、回放确定性〔同种子步骤流逐行相同——B1 AC-33 形态〕、存档/RNG 快照往返、A1×A2 双包含端到端）落地时随批建 tests/integration/ 迁入；各 GDD 登记的 deferral 集成用例以对侧登记为生效条件。

断言计数双口径（2026-10-08 迭代 19 卡① T4 订正）

历史 README 写死「752+ 断言/十五套件」必然漂移，改为两种口径并注明语义：

运行时口径：python tools/run_smoke.py 打印的通过项数（迭代 19 卡①分支基点实测 840 项 0 失败，2026-10-08；master 合并卡②④后为 846——随断言面增减浮动，以当次跑测打印为准）——循环内断言按执行次数计。
静态口径：game/smoke/ 源码 check( 调用点计数（2026-10-08 本分支实测 764 处）——按源码位置计，一处在循环内即多次执行，故两口径数值不同且各自浮动，禁互相换算或写死。

Running Tests

# 单元套件（双载体之一）——Windows 须用 console 版 exe 取 stdout；工作目录 = game/（含 project.godot 那一层）
godot --headless --script tests/run_all.gd          # 统一入口（本地闸 02 闸调用点）
godot --headless --script tests/unit/example_test.gd

# 场景探针（双载体之二）——以探针场景为运行目标，走完整项目引导（autoload 在位）
godot --headless --path . res://smoke/<probe>.tscn

# 本地闸必须配外部 wall-clock 超时（引擎无死锁探测；run_all_gates.sh 已内置）
timeout 120s godot --headless --script tests/run_all.gd

单元/契约套件状态（单元测试与契约层批 2026-09-28 立基，后随迭代 7/8 增补）：_suites() manifest 已登记实跑 26 套件（2026-10-16 迭代 29 T1：样板件 example_test.gd 退出生产 manifest，27 → 26；fog_lantern_wiring_test 随提灯载体退役摘除在前）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/提灯装配链）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集）；致命类独立进程 expect=1。期望值一律由表读值推导（零玩法数值字面量）、随机只经 RngService 统一流。

协议要点（D2 冒烟协议）：

冒烟脚本 extends SceneTree 以获得 quit(code)；成功 quit(0)、失败 quit(1)
--script 模式不加载 autoload 且不注册全局标识符（裸引用 ConfigDB = parse error）——ConfigDB/RngService 由脚本显式实例化，core 一律构造注入
致命类用例独立进程，runner manifest 登记"调用 → 期望退出码"
每用例先 reset_diagnostics()（诊断收集器协议）
期望值由表读值推导，不写死玩法数值

Test Naming

Files: [system]_[feature]_test.gd（领域命名，禁 ID 前缀——design/dev/code-conventions.md）
Functions: test_[scenario]_[expected]
Example: reward_roll_test.gd → test_power_interval_rolls_within_bounds()

Story Type → Test Evidence

Story Type	Required Evidence	Location
Logic	Automated unit test — must pass	`tests/unit/[system]/`
Integration	Integration test OR playtest doc	落地时随批建 `tests/integration/[system]/`（目录已删空壳，章程见上）
Visual/Feel	Screenshot + lead sign-off	`tests/evidence/`
UI	Manual walkthrough OR interaction test（场景探针为首选）	`tests/evidence/`
Config/Data	Smoke check pass	`design/qa/`

Static Scan（提交前本地跑）

tests/static_scan.sh 实现静态扫描域 S1–S8 的可执行子集；规则全集与动机见 design/dev/architecture/architecture.md「测试与质量域」节。新违规案例必须先补扫描规则再修码。

本地闸（唯一验收门禁）

本仓库无远端、无 CI——验收只在本地发生，跑 tools/run_all_gates.sh（全量）是收口唯一入口，跑完写回执 game/tests/.gates/receipt.json，合回 master 由 worktree-guard 校验回执。闸清单的唯一定义处就是那个脚本，本文档不另列清单（清单散落多份文档正是历史漏跑闸的成因）。

判定三硬闸（各闸一律适用，缺一即判定有洞）： ①退出码为唯一权威判据——日志里的 PASS 串只是日志，不作判据； ②脚本错误扫描命中即红——GDScript 的 SCRIPT ERROR / Parse Error 不改进程退出码、不计失败数，且会静默中断所在函数的剩余断言，只能由外部扫输出（闸件 tools/error_scan.py，错误标记与 tools/run_smoke.py 同源）； ③断言数为零即红——test_kit.gd 的 finish() 在零断言时返回专用退出码 2（与「断言失败=1」区分，避免致命类套件的 expect 协议把它当成预期结果放过）。

gdUnit4 维持 deferred：不引入第三方测试框架，本仓库在既有双载体（--script 套件 + 探针场景）内解决。

术语（本项目内的唯一语义）

词	语义	载体
冒烟（smoke）	秒级存活检查——能否启动、能否加载表、能否进主屏。判断「这版还活着吗」，不判断「这版对不对」	`game/smoke/` 的存活面
单元套件	隔离的公式/状态机/纯逻辑断言面，逐套件独立进程实跑	`game/tests/unit/`、`run_all.gd`
场景探针	以探针场景为运行目标、走完整项目引导（autoload 在位）的 UI/场景断言	`game/smoke/*.tscn`、`probe_gate.sh`
集成用例	跨系统测试（Core-Core／回放确定性／存档⇄RNG 往返／端到端）	`game/tests/integration/`

⚠ 两处历史遗留命名，读代码时别被字面骗了：tools/run_smoke.py 之名来自冒烟，但它承载的是系统级断言面（1127 项检查，远不止存活检查）；game/smoke/ 之名同理，里面既有存活面也有系统级断言与场景探针。判定「是不是冒烟」看语义，不看文件名。

7.5 KiB Raw Blame History Unescape Escape