docs(测试工具手册): game/tests/README.md 升级手册形态——头部三线分工声明（介绍=手册／规则与时机=test-conventions／闸清单=run_all_gates.sh 唯一落点）＋工具速查表八件（判什么/结果谁判/什么时候用）＋测量件发起规则指路；test-conventions.md 分工句原位扩一行指针（不推移行号）；待办清单登记 gdstyle 引入条目（工程直入，2026-10-24 会话实测三件证据）。全量域闸绿（回执 full 档，07 doc_link 较基线改善）。gdstyle v0.4.0 兼容实测见待办清单条目现状节
This commit is contained in:
DKChan committed
1 parent
59bf85c169
commit
53426fd073
3 files changed
+31
-2
No files matched your search
@@ -1,7 +1,7 @@
|
||||
# 测试规范（Dungeon Sweeper）
|
||||
|
||||
> 约束范围：`game/probe/ 与 game/sim/`、`game/tests/` 与一切场景探针的编写与验收。
|
||||
> 分工：测试**执行许可**（什么时候允许跑测试）归 AGENTS.md「硬性红线·测试执行两入口铁规」；**跑什么闸、什么顺序**归 `tools/run_all_gates.sh`（脚本即清单，本文与 AGENTS.md 均不另列）；本文管测试怎么写、怎么算合格。
|
||||
> 分工：测试**执行许可**（什么时候允许跑测试）归 AGENTS.md「硬性红线·测试执行两入口铁规」；**跑什么闸、什么顺序**归 `tools/run_all_gates.sh`（脚本即清单，本文与 AGENTS.md 均不另列）；本文管测试怎么写、怎么算合格。每件测试工具**是什么、判什么、怎么单独跑、什么时候适合单独用**——见 `game/tests/README.md`（测试工具手册），本文不重复工具介绍。
|
||||
|
||||
**写任何测试前必须通读本文。**
|
||||
|
||||
|
||||
+22
-1
@@ -1,4 +1,4 @@
|
||||
# Test Infrastructure — Dungeon Sweeper
|
||||
# Test Manual — Dungeon Sweeper（测试工具手册）
|
||||
|
||||
**Engine**: Godot 4.7.2-stable（GDScript 单语言）
|
||||
**Test Framework**: 标准四级测试层（冒烟／单元／集成／系统）＋ headless 场景探针与渲染 golden；gdUnit4 **deferred**（D2 OQ1 关闭形态——本仓库不引第三方测试框架，需求见下「门禁」节）
|
||||
@@ -6,6 +6,11 @@
|
||||
**Setup date**: 2026-09-12（2026-09-27 `7f24b640` 三层收敛：根 tests/ 并入 `game/tests/`、docs 并入 `design/engineering/`、production 解散）
|
||||
**参考实现**: `game/probe/`（场景探针族）· `game/sim/`（测量/诊断/模拟驱动件）（场景探针族——正式工程的活样板；系统测试断言面过渡宿主 `smoke_all.gd` 亦在此，迁移归断言迁移批）
|
||||
|
||||
本手册是测试面每件工具的介绍处：**它是什么、判什么、怎么单独跑、结果由谁判、什么时候会用它**。
|
||||
分工三线——介绍归本文；**规则与时机**（什么时候必须跑哪些测试、测试怎么写、怎么算合格）归
|
||||
`design/engineering/test-conventions.md`；**收口验收跑哪几道闸**（闸清单与改动域划分）只在
|
||||
`tools/run_all_gates.sh` 脚本内定义一处，本手册不另列闸清单。
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
@@ -47,6 +52,21 @@ tests/
|
||||
|
||||
两口径数值不同且各自浮动，禁互相换算或写死。
|
||||
|
||||
## 工具速查（逐件：判什么 / 结果谁判 / 什么时候用）
|
||||
|
||||
| 工具 | 判什么 | 结果谁判 | 什么时候会用它 |
|
||||
|---|---|---|---|
|
||||
| `tools/run_smoke.py`（冒烟测试） | 这版能否启动、能否加载表、能否进主屏——零逻辑判定 | 退出码＋脚本错误扫描 | 开机路径／表加载改动后的快速自检；收口由闸编排 |
|
||||
| `tools/run_system_test.py`（系统测试） | 真实玩法路径的行为断言面（推理→战斗→结算→进度推进） | 退出码＋脚本错误扫描 | 玩法链路改动的调试期确认 |
|
||||
| `tests/run_all.gd`（单元与集成） | 公式／状态机／契约／跨系统闭环（40 套件 manifest） | 退出码＋三硬闸（见下） | 新套件单跑调试；逻辑改动的最小单元复跑 |
|
||||
| `tools/probe_gate.sh`（场景探针，`--click`／`--full` 两模式） | UI 可达性、可见性、状态——真实实例化场景＋真实输入路径 | 探针自检＋退出码 | 新增 UI 区域的配套探针直跑与断言复核 |
|
||||
| `tools/render_gate.sh`（渲染 golden） | 画面基线——截图与基线图逐像素容差比对 | golden 比对脚本（依赖 PIL） | 主题／素材／排版类改动；窗口化运行，需开显示器 |
|
||||
| `game/tests/static_scan.sh`（S 域） | 项目纪律：RNG 单点／core 纯度／类型标注／文件头／注释禁词／旧符号残留 | 退出码（逐规则 FAIL 行） | 改产品码前后的快速自检；新增纪律先补扫描规则再修码 |
|
||||
| `tools/parity_anchor.py`（回放对拍） | 同种子下三变体逐位确定性 | 工具脚本逐位比对 | 本批触及数值／存档／RNG／结算面时；须用户批准发起 |
|
||||
| 测量件（`game/sim/`，逐件见下「游离脚本台账」） | 期望／分布读数——只给读数，不判对错 | 人工读 stdout 或配套工具脚本 | 调参与归因；MC 类一律用户发起（档位表见 `sim-data/README.md`「MC 采集档位表」） |
|
||||
|
||||
> 单件直跑是调试期最窄确认手段，**不构成验收**——验收只有 `tools/run_all_gates.sh` 一个入口（判定三硬闸见下「本地闸」节）。
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
@@ -121,6 +141,7 @@ timeout 120s godot --headless --script tests/run_all.gd
|
||||
|
||||
> **纪律**：本表是这些件的唯一在册处。新增手动测量脚本必须同批登记（用途 + 触发方式 + 结果由谁判）；
|
||||
> 退役走 `design/engineering/doc-conventions.md` 第 10 节退役规则，禁止「没看见＝死件」式清理。
|
||||
> 测量类批量的发起规则（档位与批准）见 `sim-data/README.md`「MC 采集档位表」——无数值改动禁重跑。
|
||||
|
||||
## Static Scan（提交前本地跑）
|
||||
|
||||
|
||||
@@ -2,6 +2,14 @@
|
||||
|
||||
本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据，正文＝现状/缺口/归属/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。
|
||||
|
||||
#### gdstyle 引入——GDScript 第三方 linter 接入检查面（2026-10-24 登记，来源=会话提及，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝2026-10-24 会话实测三件：①本机已装 gdtoolkit 4.5.0（gdlint/gdparse，PyPI 最新即此版）对 3 个在役文件解析假红（presentation/curio_interact_controller.gd、tests/system_test.gd、probe/ui_click_probe.gd——不认 Godot 4.7 新语法，Godot 自家解析器对三者全过）；②候选 gdstyle v0.4.0（github.com/atelico/gdstyle，Rust 单二进制）对上述 3 文件全过、全工程 194 个 .gd 仅 1 处解析误报（core/rng_service.gd 头部 INT64_MIN 负字面量，Godot 特判放行，单条可豁免）；③gdck v0.8.0 同测 3 文件挂 2，出局。价值面＝质量类规则（duplicated-load／await-in-loop／allocation-in-loop）是自建 grep 闸查不到的补充信号；格式类规则与 S9/S10 重叠、应全关。用户 2026-10-24 立项引入。
|
||||
|
||||
**归属**：tools/ 检查面与测试基建。执行形态＝非迭代批：gdstyle.toml 落仓库（只开质量类规则）＋版本锁定，先非闸跑全量摸存量，再借闸机「存量基线·零新增」机制收编进 09 静态扫描域；闸件改动按 test-conventions 配变异验证。
|
||||
|
||||
**状态**：待写卡
|
||||
|
||||
#### 测试术语与层级重构批 A——测试命名＋频率规则＋新冒烟测试（2026-10-22 登记，来源=会话提及，设计面=工程直入）
|
||||
|
||||
**现状**：测试域名实分离（名叫冒烟的载体实为千项断言面）、每轮跑闸频率过高、测试金字塔倒挂的规则重构，合同＝reports/提案-测试术语与层级重构方案-2026-10-22.md（v2，2026-10-22 用户裁决全部闭合、待裁点清零）。批 A＝非迭代批（规则与闸件批），用户 2026-10-22 直接下开工令执行：待办清单登记 → 改规则（process-conventions／roadmap loop 规范／术语表退役词对照／AGENTS.md 规则行）→ 写新冒烟测试（game/tests/smoke_boot.tscn/.gd＋tools/run_smoke.py 重写）与系统测试宿主（tools/run_system_test.py＋game/tests/system_test.gd 薄壳）→ 改闸机键映射（新增 00 冒烟测试、01 改系统测试、02 改单元与集成测试）→ 改描述性文档与 iter 技能三副本 → 全量域闸验证。批 B（断言迁移，用户特批免卡直改 game/）停机等用户发令，不在本条执行面。
|
||||
|
||||
Reference in new issue
Block a user