374 lines
56 KiB
Markdown
374 lines
56 KiB
Markdown
# Test Manual — Dungeon Sweeper（测试工具手册）
|
||
|
||
**Engine**: Godot 4.7.2-stable（GDScript 单语言）
|
||
**Test Framework**: 标准四级测试层（冒烟／单元／集成／系统）＋ headless 场景探针与渲染 golden；gdUnit4 **deferred**（D2 OQ1 关闭形态——本仓库不引第三方测试框架，需求见下「门禁」节）
|
||
**门禁**: 本地闸——`tools/run_all_gates.sh`（收口唯一验收入口，按改动域选档 `--code`／`--docs`，跨两域或改闸件本身不带参数＝全量；代码域 02 按关联档选套件，算法与套件族映射表只在脚本内定义）。本仓库**无远端、无 CI**（`.github/workflows/` 已删除，不建不留不参考）；闸清单与域划分只在本脚本定义，文档不另列
|
||
**Setup date**: 2026-09-12
|
||
**参考实现**: `game/probe/`（场景探针族）· `game/sim/`（测量/诊断/模拟驱动件）（场景探针族——正式工程的活样板；系统测试断言面过渡宿主 `smoke_all.gd` 亦在此，迁移归断言迁移批）
|
||
|
||
本手册是测试面每件工具的介绍处：**它是什么、判什么、怎么单独跑、结果由谁判、什么时候会用它**。
|
||
分工三线——介绍归本文；**规则与时机**（什么时候必须跑哪些测试、测试怎么写、怎么算合格）归
|
||
`design/engineering/test-conventions.md`；**收口验收跑哪几道闸**（闸清单与改动域划分）只在
|
||
`tools/run_all_gates.sh` 脚本内定义一处，本手册不另列闸清单。
|
||
|
||
## Directory Layout
|
||
|
||
```
|
||
tests/
|
||
unit/ # 单元测试（公式/状态机/纯逻辑，隔离断言）——extends SceneTree + quit(code)
|
||
integration/ # 集成测试（跨系统闭环——与 unit/ 同一入口同一协议，见下「测试层级」节）
|
||
smoke_boot.tscn/.gd # 冒烟测试——极小启动场景（真实开机路径存活检查）
|
||
system_test.gd # 系统测试宿主薄壳（SceneTree＋构造注入；断言迁移批后承接 smoke_all.gd）
|
||
smoke/ # critical-paths.md——人工 gate 清单（/smoke-check 读取）
|
||
evidence/ # 截图与人工签核记录
|
||
run_all.gd # 单元与集成测试统一入口（套件 manifest 协议，D2 AC-2b）
|
||
static_scan.sh # 静态扫描域 S1–S12 可执行子集
|
||
```
|
||
|
||
## 测试层级（标准四级＋UI 探针）
|
||
|
||
| 层 | 判什么 | 承载 | 入闸方式 |
|
||
|---|---|---|---|
|
||
| **冒烟测试** | 这版活着吗——能否启动、能否加载表、能否进主屏。零逻辑判定 | `tests/smoke_boot.tscn/.gd`（以项目运行目标拉起＝真实开机路径） | `run_smoke.py`（冒烟测试闸） |
|
||
| **单元测试** | 领域类的原子行为对不对（公式/状态机/纯逻辑）——从对外方法进、断言钉对外可观测面（写法判据见 test-conventions §8.2） | `tests/unit/` | `run_all.gd` manifest（单元与集成测试闸） |
|
||
| **集成测试** | 跨系统的闭环对不对 | `tests/integration/` | 同上（与单元测试同一入口、同一协议） |
|
||
| **系统测试** | 启动真实工程走真实玩法路径 | 过渡期 `game/probe/smoke_all.gd`（断言迁移批后＝`tests/system_test.gd`） | `run_system_test.py`（系统测试闸） |
|
||
| **UI 探针＋渲染 golden** | 跑起来之后 UI 与场景切换对不对；画面基线 | `game/probe/*.tscn` 探针 | `probe_gate.sh`（场景探针闸）、`render_gate.sh`（渲染闸） |
|
||
|
||
> **integration/ 已建承载**。
|
||
> 首个集成用例 = `save_rng_roundtrip_test.gd`（存档⇄RNG 快照往返）。章程登记的四类集成用例里，
|
||
> Core-Core 与 A1×A2 端到端仍随属主批增量登记；各 GDD 登记的 deferral 集成用例以对侧登记为生效条件。
|
||
>
|
||
> **分层判据**：能不能在 `--script` 模式下不加载 autoload 就验完？能 = 单元测试；
|
||
> 需要两个以上真实系统协同并走落盘/落库 = 集成测试；需要完整项目引导与场景树 = 冒烟／系统／UI 探针。
|
||
|
||
**能力清单**（能力义务清单：一行＝一个玩家或系统可观测的能力，只宣布「要验证什么」，不记「是否已验证／是否跑过」；定位＝实现指导＋阅读导航＋义务声明，代表用例只给指针、不复制断言细节。七段＝核心四域＋排雷循环＋表现与支撑＋数据配置与跨系统契约，行数随清单生长不在此记账；系统文档逐篇对照见下方「覆盖域表」）：
|
||
|
||
> **本表地位**：本表是唯一能力义务清单（维护锚＝test-conventions §8.3 清单归属＋§8.9 三层模型）。本表不是闸，不替代改动—验收对照表、体验验证清单与静态纪律；已落地行的唯一事实源是 `game/tests/` 下的测试代码，计划中的行由需求卡片锚定（见维护规则）。
|
||
>
|
||
> **代表用例口径**：写 `文件:函数`，每行 1–3 个；函数内可含 `Kit.check_quiet` 静默通道（逐断言提取器口径外，test-conventions §5.2 已备案）——本表以函数为锚，不受该工具局限影响。计划中的用例＝卡内定死的测试名，实现落地后转为代码实锚（机检双通道：代码在或卡在，test-conventions §8.9）。
|
||
>
|
||
> **维护规则（写卡段维护，实现批禁写本表）**：写需求卡片时当场入表——本批新增能力当场增行（真实入口取自设计文档已定的入口；代表用例＝卡内定死的计划测试 `文件:函数`，实现照单落名，名实不符＝卡片没写清＝停卡退回）；受影响存量行（入口／用例名变更）同批更新；能力退役删行。批末收尾只核对表上名字与实际落地一致（改名则回表），不刷任何批次字段（test-conventions §8.3／§8.9）。
|
||
>
|
||
> **旅程补录方法**：新旅程＝加一行，「系统」列写涉及边界；源＝architecture「API 边界」表＋「数据流」存档/读档路径＋各 GDD 登记的 deferral 集成用例。
|
||
|
||
**旅程段一：开机与存档**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 存档写盘⇄读回往返保真 | 存档序列化 | `SaveManagerCore.write_to_disk()`／`load_from_disk()` | `save_manager_domain_test.gd:_smoke_save` |
|
||
| 三槽位隔离与激活失败回滚 | 存档序列化 | `SaveManagerCore.activate_slot()`／`create_slot()`／`delete_slot()` | `save_slot_isolation_test.gd:_test_three_slot_roundtrip_and_isolation`；`save_slot_isolation_test.gd:_test_activate_failure_restores_previous_slot` |
|
||
| 槽位摘要窥视与坏槽三态 | 存档序列化 | `SaveManagerCore.peek_slot_summary()` | `save_slot_summary_test.gd:_test_peek_three_slots_distinct_values`；`save_slot_summary_test.gd:_test_peek_empty_and_unreadable_states`；`save_slot_summary_test.gd:_test_peek_zero_side_effect` |
|
||
| 启动态无激活不写盘 | 存档序列化 | `SaveManagerCore.has_write_target()`／`write_to_disk()` | `save_boot_no_activate_test.gd:_test_write_rejected_without_target`；`save_boot_no_activate_test.gd:_test_out_of_range_slots_rejected` |
|
||
| 旧档迁移链与断点续玩零跳号（集成） | 存档序列化×冒险结构 | `SaveManagerCore.load_from_disk()`（内置迁移链）× `AdventureRunner.resume_adventure()` | `save_rng_roundtrip_test.gd:_test_old_version_save_migrates_and_resumes` |
|
||
| 存档⇄RNG 快照往返保真（集成） | 存档序列化×RNG 服务×冒险结构 | `AdventureRunner.start_adventure()` → `SaveManagerCore.write_to_disk()`／`load_from_disk()` | `save_rng_roundtrip_test.gd:_test_disk_roundtrip_preserves_breakpoint` |
|
||
| RNG 统一流派生与取号账本 | RNG 服务 | `RngServiceCore.derive_at()`／`open_stream()`／`counter()` | `rng_service_test.gd:_test_derive_determinism`；`rng_service_test.gd:_test_stream_draw_determinism`；`rng_stream_boot_test.gd:_smoke_initialize` |
|
||
| 断点片段往返与续玩幂等 | 冒险结构×关卡节点地图 | `LevelRunner.breakpoint_fragment()`／`restore_fragment()`；`AdventureRunner.resume_adventure()` | `breakpoint_resume_test.gd:_init` |
|
||
| 跨系统附随面：事件日志落盘与断点附随件（集成） | RNG 服务×存档序列化×冒险结构 | `RngServiceCore.new_adventure()`（开事件日志会话）；`SaveManagerCore.breakpoint_snapshot()`（断点附随键） | `cross_system_flow_test.gd:_rng_event_log_session`；`cross_system_flow_test.gd:_feats_breakpoint_roundtrip` |
|
||
|
||
**旅程段二：冒险开局与选路**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 冒险生命周期：开局受理／三关序列／败北线 | 冒险结构 | `AdventureRunner.start_adventure()`／`continue_to_next_level()` | `adventure_feats_test.gd:_smoke_adventure_api`；`adventure_feats_test.gd:_smoke_adventure`；`hero_ledger_test.gd:_init` |
|
||
| 专长（奇物）授予与凭证保底 | 奇物 | `AdventureRunner.present_node_curio()`／`feats_held()` × 效果引擎兑付 | `adventure_feats_test.gd:_smoke_feats`；`feat_vouchers_test.gd:_init` |
|
||
| 节点图生成合法性与同种子复现 | 关卡节点图生成 | `NodeMapGenerator.generate()`／`validate_output()` | `node_map_generator_test.gd:_test_output_ok`；`node_map_generator_test.gd:_test_reproducible`；`node_map_generator_test.gd:_test_exit_structure` |
|
||
| 节点图生长递增与无解 fail-fast | 关卡节点图生成 | `NodeMapGenerator.generate()`／`is_fatal()` | `node_map_growth_test.gd:_test_growth`；`node_map_growth_test.gd:_test_fatal_subprocess` |
|
||
| 节点图参数读表与域单点（三参数驱动产物／生成器侧可行性保留） | 关卡节点图生成 | `NodeMapGenerator.generate()`／`LevelGenParams.validate()` | `node_map_generator_test.gd:_test_gen_params_table_driven`；`table_structure_guard_test.gd:_test_level_gen_new_fields`；`level_gen_params_test.gd:_init`；`encapsulation_p2_sweep_test.gd:_init` |
|
||
| 起关／选路／断点重生成同图（集成） | 关卡节点地图×关卡节点图生成×冒险结构 | `LevelRunner.start_level()`／`start_level_external()`／`pick_next_node()`；`AdventureRunner.resume_adventure()` | `node_map_determinism_test.gd:_smoke_generated_map_determinism` |
|
||
| 信息迷雾类型可见性 | 关卡节点地图 | `LevelRunner.type_visible_ids()` | `level_map_type_vis_test.gd:_test_layer_distance`；`level_map_type_vis_test.gd:_test_boss_exempt`；`level_map_type_vis_test.gd:_test_resume_rebuild`；`level_map_info_fog_test.gd:_initialize` |
|
||
| 关卡表消费侧校验与关卡推进 | 关卡节点地图×数据配置 | `LevelTable.validate_graph()`；`LevelRunner.start_level()` | `level_table_validate_test.gd:_test_positive`；`level_table_validate_test.gd:_test_negative`；`level_shop_economy_test.gd:_smoke_level` |
|
||
|
||
**旅程段三：战斗结算**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 伤害公式与掷点乘区 | 战斗结算 | `DamageMath.pool_damage()`／`roll_discount_percent()`／`rolled_component()` | `damage_math_test.gd:_test_pool_damage`；`damage_math_test.gd:_test_roll_discount_percent`；`roll_multiplier_test.gd:_smoke_armor_roll` |
|
||
| 伤害单据编排与回放 | 战斗结算 | `DamageController.submit()`／`open_ticket()`／`flush()` | `damage_controller_test.gd:_run_recipe_sequence`；`damage_controller_test.gd:_test_five_recipes_and_replay` |
|
||
| 效果发射端口单点 | 战斗结算 | `BattleOrchestrator.begin_battle()`（真实装配链端口接线＋合成行闭面守卫经 `DamageController.flush_submit()` 承伤路径） | `effect_port_test.gd:_smoke_effect_port_wiring`；`effect_port_test.gd:_test_business_classes_engine_free`；`effect_port_test.gd:_test_biz_fact_face_closed` |
|
||
| 轮内流与结算五段全序 | 战斗结算 | `BattleOrchestrator.begin_battle()` | `round_flow_skill_pool_test.gd:_smoke_full_battle`；`round_flow_skill_pool_test.gd:_smoke_settlement_segments`；`settle_segments_test.gd:_init`；`settlement_wiring_snapshot_test.gd:_init`；`encapsulation_sweep_test.gd:_init` |
|
||
| 技能池数据面与回放独立 | 敌人系统 | `BattleOrchestrator.begin_battle()`（技能池抽号／校验） | `round_flow_skill_pool_test.gd:_smoke_skill_pool_data`；`round_flow_skill_pool_test.gd:_smoke_skill_pool_replay_independence`；`trigger_cond_test.gd:_init`；`pool_case_d_test.gd:_init` |
|
||
| Boss 半血解锁技门控 | 敌人系统 | `BattleOrchestrator.begin_battle()`（Boss 行） | `skill_unlock_test.gd:_test_gate_predicate`；`skill_unlock_test.gd:_test_latch_irreversible` |
|
||
| 封印与极性路由／不可逆 | 地图战斗资源×战斗结算 | 效果引擎 × `BattleOrchestrator.begin_battle()` | `seal_polarity_test.gd:_smoke_seal_ap_exhausted`；`seal_polarity_test.gd:_smoke_seal_irreversible_quadrants`；`seal_polarity_test.gd:_smoke_polarity_routing` |
|
||
| 变异布置门控 | 地形变异 | `BattleOrchestrator.begin_battle()`（变异布置段） | `variant_placement_test.gd:_smoke_variant_placement`；`variant_placement_test.gd:_smoke_global_variant`；`variant_placement_test.gd:_test_pack_min_from_table` |
|
||
|
||
**旅程段四：奖励、经济与局外成长**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 清图奖励双份与零路径 | 地图战斗资源 | `BattleOrchestrator.begin_battle()` → 步骤流行（`source_class=clear_reward`） | `seal_polarity_test.gd:_smoke_clear_reward_chain`；`seal_polarity_test.gd:_smoke_clear_reward_zero_paths` |
|
||
| 奖励三选一候选／刷新付费／呈现 | 奇物×节点奖励屏 | `AdventureRunner.present_node_curio()`（数据面）；奖励节点覆盖层场景（呈现面） | `curio_refresh_paid_test.gd:_init`；`reward_overlay_test.gd:_run` |
|
||
| GP 钱包／escrow／商店收口／共享池 | 地图战斗资源×商店 | `LevelRunner.shop.buy_product()`／`shop.player_request_refresh()`／`LevelRunner.close_wallet()`／`shop.set_shop_pool()` | `level_shop_economy_test.gd:_smoke_gp_wallet`；`level_shop_economy_test.gd:_smoke_shop_room`；`level_shop_economy_test.gd:_smoke_shop_pool`；`level_shop_economy_test.gd:_test_spend_discount_from_rule_key` |
|
||
| 货架位数读表（进店与重抽同源） | 商店 | `ShopSession.shop_shelf()`（货架构建与重抽同源面） | `level_shop_economy_test.gd:_test_shelf_size_from_table` |
|
||
| 元进度入账与锻造两轴 | 元进度×锻造工坊 | `MetaStateStore.apply_adventure_summary()`／`MetaStateStore.spend_keystone()`／`MetaStateStore.set_forge_route_level()` | `meta_progression_forge_test.gd:_meta_pricing_and_buy`；`meta_progression_forge_test.gd:_smoke_forge_axes` |
|
||
| 锻造定价与购买闭环（全路线价格梯/多级购买扣款/拒购零副作用） | 锻造工坊 | `ForgeTable.level_price()`／`MetaProgression.forge_buy_level()` | `forge_table_test.gd:_test_price_ladder`；`meta_progression_forge_test.gd:_meta_pricing_and_buy`；`meta_progression_forge_test.gd:_test_forge_buy_reject` |
|
||
| 锻造与相邻通道隔离（祝福件购买锻造零变化/默认轴与钥匙解耦/甲型切换双轴可感） | 锻造工坊×元进度 | `MetaProgression.forge_select()`／`hero_type_axes()`／商店购买口 | `meta_progression_forge_test.gd:_test_blessing_no_forge_leak`；`meta_progression_forge_test.gd:_test_default_axes_pre_key`；`meta_progression_forge_test.gd:_test_armor_switch_dual_axes` |
|
||
| 天赋树购买与六键合成 | 天赋树 | `MetaProgression.tree_buy()`／`MetaStateStore.tree_state()`／`MetaStateStore.set_tree_level()` | `meta_progression_forge_test.gd:_smoke_tree`；`meta_progression_forge_test.gd:_smoke_tree_rules`；`tree_rules_v11_test.gd:_init`；`tree_requires_level_test.gd:_init` |
|
||
| 规则键参数读表（六键参数字典校验与激活侧透传） | 天赋树 | `MetaTreeTable.validate()`／`EffectEngine.rebuild()`／`MetaProgression.tree_rules()` | `tree_rules_v11_test.gd:_test_rule_key_params` |
|
||
| 秘宝结构冻结与 12 件效果 | 秘宝 | `TreasureItems.add_item()`／`query_inventory()`／`validate_use()` | `treasure_items_test.gd:_init`；`treasure_effects_test.gd:_init` |
|
||
|
||
**旅程段五：排雷循环**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 棋盘按参数行出图、数字恒真 | 棋盘生成 | `BoardGenerator.generate()` | `board_generator_test.gd:_test_generate_shape_and_mines`；`board_generator_test.gd:_test_digits_equal_neighbor_mine_count`；`board_generator_test.gd:_test_spawn_edge_from_table` |
|
||
| 出生区边长表单点（布雷域基／R₀ 下限／剃雷域半径全由 spawn_edge 导出） | 棋盘生成 | `BoardGenerator.generate()`／`BoardGenTable.validate()` | `board_generator_test.gd:_test_spawn_edge_from_table` |
|
||
| 同参数同种子逐位复现、异种子不退化 | 棋盘生成 | `BoardGenerator.generate()` | `board_generator_test.gd:_test_same_seed_bit_identical`；`board_gen_reward_test.gd:_smoke_board_generator` |
|
||
| 可推理率与清图可达（合法性先于质量分）、重试有界、降级诚实 | 棋盘生成 | `BoardGenerator.measure_inferability()`／`BoardGenerator.is_clearable()` | `board_generator_test.gd:_test_clearable_and_inferability_selfconsistent`；`board_generator_test.gd:_test_target_mine_count_single_source`；`board_gen_reward_test.gd:_smoke_board_generator` |
|
||
| 装板与开局免费展开（封锁格无资源、计入清图） | 排雷玩法 | `MinesweeperRules.install_board()` | `minesweeper_rules_test.gd:_test_install_invariants`；`seal_polarity_test.gd:_smoke_resource_surface` |
|
||
| 挖／封印合法性与可辨拒绝（拒绝零副作用） | 排雷玩法 | `MinesweeperRules.settle_batch()` | `minesweeper_rules_test.gd:_test_dig_face_rules`；`minesweeper_rules_test.gd:_test_seal_place`；`minesweeper_rules_test.gd:_test_reject_out_of_catalog` |
|
||
| 棋盘揭示预览只读口（零状态写入／与实挖揭示集同口径） | 排雷玩法 | `MinesweeperRules.preview_reveal()` | `minesweeper_rules_test.gd:_test_preview_reveal_readonly` |
|
||
| 封印不可逆与挖开封印格放行（兑付改判四情况） | 排雷玩法 | `MinesweeperRules.settle_batch()` | `seal_polarity_test.gd:_smoke_seal_irreversible_quadrants`；`minesweeper_rules_test.gd:_test_seal_place` |
|
||
| 棋盘封印印记呈现 | 排雷玩法 | `BoardCellUnit.edge` → `SealMarkLayer.setup()` | `seal_mark_params_test.gd:_test_param_values`；`seal_mark_params_test.gd:_test_fog_gate` |
|
||
| AP 扣费、末点耗尽即收轮与战斗收束清零 | 行动经济 | `MinesweeperRules.settle_batch()`（→`ActionEconomy.try_spend()`／`ActionEconomy.notify_combat_end()`） | `seal_polarity_test.gd:_smoke_seal_ap_exhausted`；`round_flow_skill_pool_test.gd:_smoke_full_battle`；`round_flow_skill_pool_test.gd:_smoke_active_refresh` |
|
||
| 停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励） | 行动经济 | `BattleOrchestrator.player_request_refresh()`／`MinesweeperRules.settle_batch()` | `round_flow_skill_pool_test.gd:_smoke_active_refresh`；`seal_polarity_test.gd:_smoke_refresh_provenance_guard`；`refresh_feats_test.gd:test_no_feats_baseline` |
|
||
| 换图系刷新链路与效果词表接线 | 行动经济×战斗结算×奇物 | `MinesweeperRules.settle_batch()`／`BattleOrchestrator.player_request_refresh()` | `effect_words_t1_test.gd:_init`；`forge_table_test.gd:_test_effect_kinds_closed`；`refresh_feats_test.gd:test_board_refresh_fact_only_on_success` |
|
||
| 换图基座：挖格产 RAP 与刷新折扣 | 行动经济×奇物 | `MinesweeperRules.settle_batch()`／`BattleOrchestrator.player_request_refresh()` | `refresh_feats_test.gd:test_reserve_on_accepted_dig`；`refresh_feats_test.gd:test_refresh_discount_gate_and_charge`；`refresh_feats_test.gd:test_double_base_stack` |
|
||
| 换图输出：刷新群伤与蓄力攻击 | 战斗结算×奇物 | `BattleOrchestrator.player_request_refresh()`→轮末 `MinesweeperRules.settle_batch(stop)` | `refresh_feats_test.gd:test_blast_defers_to_combat_segment`；`refresh_feats_test.gd:test_charge_layers_consumed_same_round`；`run_time_fatal_test.gd:_init` |
|
||
| 换图生存：全局固定减伤与轮末恢复 | 战斗结算×奇物 | `BattleOrchestrator.player_request_refresh()`→敌方攻击／危险格／错误封印／地形真实受伤入口 | `refresh_feats_test.gd:test_all_hero_damage_paths_emit_once`；`refresh_feats_test.gd:test_stone_mitigation_all_damage`；`refresh_feats_test.gd:test_rest_rotation_cap_and_clear` |
|
||
| 换图资源：刷新固定 GP 收益 | 战斗结算×奇物 | `BattleOrchestrator.player_request_refresh()` | `refresh_feats_test.gd:test_mine_profit_gp` |
|
||
| 下轮行动点修正排队与兑现 | 行动经济 | `ActionEconomy.pending_ap_delta()`（排队经 `ActionEconomy.queue_ap_delta()`，写入方为效果引擎） | `seal_polarity_test.gd:_smoke_negative_dictionary`；`feat_vouchers_test.gd:_init` |
|
||
|
||
**旅程段六：表现与支撑**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 拒绝反馈分面可辨与未知兜底文案 | HUD框架 | `HudPresenter.outcome_text()` | `hud_presenter_test.gd:_test_reject_text_by_reason`；`hud_presenter_test.gd:_test_unknown_reason_fallback`；`hud_presenter_test.gd:_test_accepted_text` |
|
||
| 结算明细带逐行呈现与排播节奏 | HUD框架 | `BattleLogView.append_row()`／`RowPacer.pace_delay_for()` | `theme_projection_test.gd:_smoke_battle_log_view`；`player_copy_sweep_test.gd:_sweep_source_names`；`pacing_queue_test.gd:_init` |
|
||
| 模态覆盖层编排与输入锁 | HUD框架 | `ModalFlow.locks_input()`／`ModalFlow.open_after_playback()` | `modal_flow_test.gd:_init`；`reward_overlay_test.gd:_run` |
|
||
| 模态句柄分域寻址面 | HUD框架 | 局内／菜单／营地三子容器句柄经注册面合同寻址（`UiRegistry.node()` 逐键取层）＋模态编排口开合（`ModalFlow.open()`／`ModalFlow.close()`） | `ui_struct_probe.gd:_modal_registry_contract`（registry 合同序段＋分域句柄段） |
|
||
| 未开格类型微光（8 邻作用集／五组色相／零玩法写入） | HUD框架 | `BoardView.type_glow_probe()`／`UiKit.glow_group_for_cell_type()` | `theme_projection_test.gd:_smoke_type_glow`；`type_glow_test.gd:_test_grouping_closed`；`type_glow_test.gd:_test_frozen_hue_face` |
|
||
| 棋盘悬停反馈（三语义光标／目标格边框／路径预览点迹） | HUD框架 | `ui_input_probe` 合成鼠标事件→`BoardView._gui_input()`；读面 `BoardView.hover_probe()` | `ui_input_probe.gd:_ready`（case①到达②禁入③路径预览三语义） |
|
||
| UI 全局主题与按钮五态（含对比度锚） | HUD框架 | `UiKit.button()`／`UiKit.primary_button()` | `theme_projection_test.gd:_smoke_global_theme`；`theme_projection_test.gd:_smoke_button_five_states`；`theme_projection_test.gd:_smoke_contrast_inks` |
|
||
| 中文字体随包与字形覆盖 | HUD框架 | `UiKit.load_font()` | `ui_font_asset_test.gd:_init`；`theme_projection_test.gd:_smoke_global_theme` |
|
||
| 地形瓦片套与格面数字可读 | HUD框架 | `TilePalette.digit_ink_mode()`／`TilePalette.normalize_floor_luma()` | `terrain_tile_sets_test.gd:_test_set_completeness`；`terrain_tile_sets_test.gd:_test_hue_domains`；`terrain_tile_sets_test.gd:_test_digit_ink_modes` |
|
||
| 站桩敌人呈现与结算演出落点 | 战斗表现 | `BattleStageView.enemy_standee_center()`／`BattleEndOverlay.open_victory()` | `standee_fx_sweep_test.gd:_init`；`pacing_queue_test.gd:_init` |
|
||
| 站桩呈现定值与素材绑定 | 战斗表现 | `UiKit.load_tex()`／`StandeeBody.name_line_probe()` | `standee_present_values_test.gd:_init` |
|
||
| 站桩显示档与素材分辨率绑定 | 战斗表现 | `StandeeBody.portrait_probe()`／`StandeeMotion.PORTRAIT_DISPLAY_H` | `standee_present_values_test.gd:_check_display_tier` |
|
||
| B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役） | HUD框架 | `BattleStageView.set_board_type()` | `stage_background_test.gd:_test_background_selection`；`stage_background_test.gd:_test_ground_layer_geometry`；`stage_background_test.gd:_test_beams_retired` |
|
||
| 战斗屏三区几何与棋盘格边长（分辨率两档×四档板型） | HUD框架 | `BoardView.set_cell_area()`（D 区可用面积 → 格边长）；读面 `BoardView.cell_size` | `layout_probe.gd:_ready`；`board_gen_reward_test.gd:_smoke_layout_cell_formula` |
|
||
| 调参测速批量模拟（逐帧步进与统计读数） | 调参测量 | `TuneSimController.run()`（调试浮窗批量模拟入口） | `tune_sim_batch_parity_test.gd:_init`（配对对拍套件） |
|
||
| sim 驱动循环单点（缺省零变化与策略/日志回调形态） | 调参测量 | `BattleDriver.drive_round()`（两参缺省与五参回调两形态） | `battle_driver_drive_test.gd:_smoke_drive_round_contract` |
|
||
| 模拟玩家 0 格连锁算子（经真实闭包，零盲挖语义保持） | 调参测量×排雷玩法 | `AutoPlayer._deduce()`（经 `perfect_action()` 装配链） | `auto_player_deduce_test.gd:_smoke_zero_chain_rule` |
|
||
| 刷新提示文案读表拼接（RAP 不足／轮上限两 toast 零字面量） | HUD框架 | `Main._on_refresh_confirmed()`（两 toast 装配面）＋`player_copy_sweep` 源扫描 | `player_copy_sweep_test.gd:_sweep_refresh_toast_no_literals` |
|
||
| 试玩日志器 ap_per_round 必填注入守卫（未注入拒绝开会话） | 表现与支撑 | `PlaytestLogger.start_session()` | `playtest_logger_guard_test.gd:_smoke_required_injection` |
|
||
| 战斗叙述与终局文案（数值带入／胜负互异） | HUD框架 | `BattleNarrator.battle_end_text()`／`BattleNarrator.boss_name()` | `battle_narrator_test.gd:_test_numeric_lines_carry_values`；`battle_narrator_test.gd:_test_end_text_differs_by_result`；`battle_narrator_test.gd:_test_boss_name_uses_boss_rowset` |
|
||
| 玩家面文案与危险格格面字形 | HUD框架 | `BoardView.rebuild()`／`StatusSlotRow.set_effects()` | `player_copy_sweep_test.gd:_sweep_board_glyph`；`player_copy_sweep_test.gd:_sweep_legend`；`player_copy_sweep_test.gd:_sweep_hero_panel` |
|
||
| 营地场景图十层铺底与门洞留空呈现 | 营地场景视图 | 进入存档→选档→进档→营地场景屏（`CampSceneView.setup_layers()` 驱动）；单元测试载入 `camp_scene_layout.tres` | `shot_probe.gd:_ready`（camp 截图段）；`camp_scene_layout_test.gd:_test_layout_hotspot_geometry` |
|
||
| 营地七物件命中区点选与分界面可达 | 营地场景视图 | 七物件命中区 → `CampSceneView._gui_input()`（命中发 `object_pressed` 信号） → 组合根开界面；**现役承载＝emit 信号直发，标「接线验证」——真输入承载待建（残险登记，2026-11-05 真实入口口径收窄）** | `ui_click_probe.gd:_ready`（七物件合成点击段） |
|
||
| 营地大门两分支确认与断点续玩接线 | 营地交互流 | 大门命中区 → 合成鼠标事件经 `push_input` 真点（`ProbeUiUtil.push_click_at`）→ ConfirmDialog 真钮（三出口）→ `main._on_confirm_accepted()`（新冒险确认）／`main._resume_from_menu()`（断点续玩） | `ui_click_probe.gd:_ready`（大门两分支段／断点确认段——真输入 push_click 驱动，2026-11-05 真输入化）；`presentation_encapsulation_sweep_test.gd:_init`（迭代52卡③组合根交接面结构性主证——pres封装 V1–V4 四组私取零命中＋新公开面正锚，2026-11-05 补链锚） |
|
||
| 四柜台拆解后五界面入口改挂与写口零回归 | 营地五界面 | 五界面意图信号 → `CampShopPresenter` → `MetaProgression.tree_buy()` 写口 | `forge_workbench_test.gd:_run`（承载类同迁断言十二项）；`ui_click_probe.gd:_ready`（写口链段） |
|
||
| 营地篝火回主菜单与笔记本改挂动线 | 营地交互流 | 笔记本命中区 → `CareerOverlay.open()`；篝火命中区 → ConfirmDialog 二次确认 → 主菜单 | `ui_struct_probe.gd:_ready`（career 段）；`screen_flow_probe.gd:_ready`（篝火／开合段） |
|
||
| 营地图鉴占位挂起态与反参照结构纪律 | 营地场景视图 | 布告板命中区 → `CampSceneView._gui_input()`（object_pressed 信号） → 图鉴占位视图；营地根态场景树审计 | `ui_struct_probe.gd:_ready`（占位禁词／禁行段）；`ui_struct_probe.gd:_ready`（结构禁词段） |
|
||
| 营地刷新单口与场景根 HUD 同步 | 营地刷新总线 | 写口尾 → `CampRefreshBus.refresh()` → 现开界面刷新＋场景根 HUD 刷新 | `ui_struct_probe.gd:_ready`（顶栏位段）；`ui_click_probe.gd:_ready`（写口尾刷新段） |
|
||
| Esc 浮窗唤起与三出口动线 | 营地 Esc 流 | 营地场景根态合成 Esc 键事件→ `main_esc_flow.on_esc_input()` → `ui.flow.open/close`；浮窗三钮 `pressed` → 三出口 | `screen_flow_probe.gd:_ready`（Esc 唤起／子界面开态不唤起／再按关窗／非营地不唤起段）；`screen_flow_probe.gd:_ready`（返回动线／设置双路径段） |
|
||
| 减动效开关存储契约（持久化回读/缺省值/引擎动效档应用） | 设置与本地化 | `SettingsStore.load_settings()`／`save_settings()`／`apply()` | `settings_store_test.gd:_test_settings_roundtrip`；`settings_store_test.gd:_test_settings_default`；`settings_store_test.gd:_test_settings_apply_chain` |
|
||
| 营地顶栏 HUD 钥石读数与刷新单口同步 | 营地 HUD 栏 | 隔离存档实例 `meta_state._add_keystone()`→ 显式触发 `CampRefreshBus.refresh(camp_data)` → `camp_hud_band.refresh()` → `keystone_badge` 读数 | `screen_flow_probe.gd:_ready`（HUD 余额读数／刷新段）；`ui_struct_probe.gd:_ready`（顶栏位结构段） |
|
||
| 营地五窗统一窗壳形态 | 营地五界面 | 七物件命中区/笔记本 → `CampSceneView._gui_input()`（`object_pressed` 信号）→ 组合根分派开窗；窗板几何（居中定尺寸 720×640 起点）/遮罩/窗内滚动面为呈现提交面 | `screen_flow_probe.gd:_step_camp_window_shell`（窗壳形态段） |
|
||
|
||
**旅程段七：数据配置与跨系统契约**
|
||
|
||
| 能力 | 系统 | 真实入口 | 代表用例（文件:函数） |
|
||
|---|---|---|---|
|
||
| 全表装载、就绪态与表清单目录对账 | 数据配置 | `ConfigDB.load_tables()`／`ConfigDB.diagnostics_count()` | `config_db_test.gd:_test_manifest_dir_sync`；`rng_stream_boot_test.gd:_smoke_initialize` |
|
||
| 进度坐标查行：精确命中／向上取整／封顶／警告去重 | 数据配置 | `BoardGenTable.resolve_row()`／`ConfigDbResolver.resolve_enemy_rowset()` | `config_db_test.gd:_test_progress_resolution`；`config_db_resolver_test.gd:_test_band_hit`；`config_db_resolver_test.gd:_test_top_band_clamp` |
|
||
| 行集寻址、行序保序与难度乘数 clamp | 数据配置×难度曲线与Boss | `ConfigDbResolver.resolve_enemy_rowset()`／`ConfigDbResolver.resolve_difficulty_modifiers()` | `config_db_resolver_test.gd:_test_rowset_order_preserved`；`config_db_resolver_test.gd:_test_row_kind_routing`；`config_db_resolver_test.gd:_test_difficulty_clamp` |
|
||
| 运行期越域致命与进程非 0 退出 | 数据配置 | `BoardGenTable.resolve_row()`／`ConfigDbResolver.resolve_enemy_rowset()` | `config_db_fatal_oob_test.gd:_trigger_oob`；`config_db_resolver_test.gd:_test_request_oob` |
|
||
| 加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域／效果类型出域 | 数据配置×秘宝×奇物 | `ConfigDB.load_tables()` | `reward_dangling_treasure_test.gd:_init`；`counter_prefix_fatal_test.gd:_assert_rejected`；`treasure_target_violation_test.gd:_init`；`effect_kind_retired_test.gd:_assert_rejected`；`extended_row_violation_test.gd:_init` |
|
||
| 表结构守卫：域校验／行序键／跨字段互锁／配额锚 | 数据配置×敌人系统×地形变异×冒险结构 | `EnemyTable.validate()`／`VariationTable.variant_pool()`／`AdventureTable.validate()` | `table_structure_guard_test.gd:_smoke_enemy_bands`；`table_structure_guard_test.gd:_smoke_variation_framework`；`table_structure_guard_test.gd:_smoke_adventure_table`；`table_structure_guard_test.gd:_test_feat_cap_required` |
|
||
| 变异表头域校验（地形变异） | 地形变异 | `VariationTable.validate()` | `table_structure_guard_test.gd:_test_variation_header_domains` |
|
||
| 难度修饰套乘：空表零行为／套乘生效／越域 clamp | 难度曲线与Boss | `UnitContainer.spawn()`／`ConfigDbResolver.resolve_difficulty_modifiers()` | `table_structure_guard_test.gd:_smoke_difficulty_table`；`config_db_resolver_test.gd:_test_difficulty_clamp` |
|
||
| Boss 出场门控（每区域恰一 Boss 终点/Boss 节点开战必选 Boss 行集） | 难度曲线与Boss | `NodeMapGenerator.generate()`／`BattleOrchestrator.begin_battle()` | `node_map_generator_test.gd:_test_boss_exit_per_region`；`boss_gate_test.gd:_test_boss_node_spawns_boss_rowset` |
|
||
| 锻造表 schema 正反与几何价格梯 | 锻造工坊 | `ForgeTable.level_price()`／`ForgeTable.route_rows()` | `forge_table_test.gd:_test_production_rows`；`forge_table_test.gd:_test_price_ladder`；`forge_table_test.gd:_test_negative_cases` |
|
||
| 系统间契约词表与受理口径：五配方互异／掷点标签成员性／增益布尔受理 | 战斗结算×数据配置×增益状态 | `DamageController.open_ticket()`／`StatusContainer.apply_effect()` | `system_contracts_test.gd:_test_damage_controller_vocabularies`；`system_contracts_test.gd:_test_rng_tag_closure`；`system_contracts_test.gd:_test_status_boolean_acceptance`；`source_guard_test.gd:_init` |
|
||
| 同名状态合并策略（叠加/累加/并存）与剩余次数语义 | 战斗循环×增益状态 | `StatusContainer.apply_effect()`（编排宿主 begin_battle 链） | `roll_multiplier_test.gd:_smoke_armor_roll` |
|
||
| 状态效果结算链（逐值衰减/到期移除/战斗结束全清/满层拒绝/独立并存/首授快照） | 增益状态 | `StatusContainer.apply_effect()`／`decay_round()`／`notify_battle_end()` | `system_contracts_test.gd:_test_status_decay_and_clear`；`system_contracts_test.gd:_test_status_stack_full_reject`；`system_contracts_test.gd:_test_status_independent_branch`；`system_contracts_test.gd:_test_status_snapshot_first_grant` |
|
||
| 状态实例按个体归属：个体隔离／全体授予逐体发／死亡即清／同体合并照旧 | 增益状态 | `StatusContainer.apply_effect()`（个体键）／`purge_owner()` | `system_contracts_test.gd:_test_status_individual_isolation`；`system_contracts_test.gd:_test_status_grant_all_per_unit`；`system_contracts_test.gd:_test_status_death_clears`；`system_contracts_test.gd:_test_status_merge_per_unit` |
|
||
| 敌方增益自体落点与乘区池按个体 | 敌人系统×战斗结算×增益状态 | 技能兑付编排链／`DamageController.clamped_pool()` | `round_flow_skill_pool_test.gd:_smoke_enemy_buff_targets_self`；`damage_controller_test.gd:_test_pool_consumption_per_unit`；`damage_controller_test.gd:_test_defender_ac_per_unit`；`battle_narrator_test.gd:_test_snapshot_effects_per_unit` |
|
||
| 敌人技能池跨表链接校验 | 数据配置×敌人系统 | `ConfigDbCrossValidator.validate_skill_pool_links()` | `config_db_cross_validator_test.gd:_test_all_links_valid`；`config_db_cross_validator_test.gd:_test_dangling_skill_id`；`config_db_cross_validator_test.gd:_test_cast_side_mismatch` |
|
||
|
||
**覆盖域表**（`design/gdd/systems/` 逐篇对照——状态三档：已覆盖／部分覆盖／未覆盖；部分与未覆盖行的缺口指待办清单条目，覆盖面提升时同批改本表）：
|
||
|
||
| 域 | 系统文档 | 能力行 | 状态 | 缺口 |
|
||
|---|---|---|---|---|
|
||
| 冒险循环 | 冒险结构.md | 冒险生命周期：开局受理／三关序列／败北线；断点片段往返与续玩幂等；起关／选路／断点重生成同图（集成） | 已覆盖 | — |
|
||
| 冒险循环 | 关卡节点图生成.md | 节点图生成合法性与同种子复现；节点图生长递增与无解 fail-fast | 已覆盖 | — |
|
||
| 冒险循环 | 关卡节点地图.md | 起关／选路／断点重生成同图（集成）；信息迷雾类型可见性；关卡表消费侧校验与关卡推进 | 已覆盖 | — |
|
||
| 冒险循环 | 奇物.md | 专长（奇物）授予与凭证保底；奖励三选一候选／刷新付费／呈现 | 已覆盖 | — |
|
||
| 冒险循环 | 难度曲线与Boss.md | Boss 半血解锁技门控；行集寻址、行序保序与难度乘数 clamp；难度修饰套乘：空表零行为／套乘生效／越域 clamp；Boss 出场门控（每区域恰一 Boss 终点/Boss 节点开战必选 Boss 行集） | 部分覆盖 | 机制面剩余缺口由「断言补齐批」承接；数值落带断言归 M4 数值批；见待办清单「能力清单覆盖缺口补齐」条 |
|
||
| 战斗循环 | 地图战斗资源.md | 清图奖励双份与零路径；GP 钱包／escrow／商店收口／共享池；封印与极性路由／不可逆 | 已覆盖 | — |
|
||
| 战斗循环 | 增益状态.md | 系统间契约词表与受理口径：五配方互异／掷点标签成员性／增益布尔受理；同名状态合并策略（叠加/累加/并存）与剩余次数语义；状态效果结算链（逐值衰减/到期移除/战斗结束全清/满层拒绝/独立并存/首授快照）；状态实例按个体归属：个体隔离／全体授予逐体发／死亡即清／同体合并照旧；敌方增益自体落点与乘区池按个体；封印与极性路由／不可逆 | 部分覆盖 | 结算链剩余缺口由「断言补齐批」承接；见待办清单「能力清单覆盖缺口补齐」条 |
|
||
| 战斗循环 | 战斗结算.md | 伤害公式与掷点乘区；伤害单据编排与回放；轮内流与结算五段全序 | 已覆盖 | — |
|
||
| 战斗循环 | 战斗表现.md | 站桩敌人呈现与结算演出落点；站桩呈现定值与素材绑定；站桩显示档与素材分辨率绑定 | 已覆盖 | 死亡灰化与减动效演出档以探针＋人工目检为终态（2026-11-02 用户裁除名，不再补自动断言） |
|
||
| 战斗循环 | 敌人系统.md | 技能池数据面与回放独立；Boss 半血解锁技门控；敌人技能池跨表链接校验 | 已覆盖 | — |
|
||
| 排雷循环 | 地形变异.md | 变异布置门控；表结构守卫：域校验／行序键／跨字段互锁／配额锚 | 已覆盖 | — |
|
||
| 排雷循环 | 排雷玩法.md | 装板与开局免费展开（封锁格无资源、计入清图）；挖／封印合法性与可辨拒绝（拒绝零副作用）；封印不可逆与挖开封印格放行（兑付改判四情况） | 已覆盖 | — |
|
||
| 排雷循环 | 棋盘生成.md | 棋盘按参数行出图、数字恒真；同参数同种子逐位复现、异种子不退化；可推理率与清图可达（合法性先于质量分）、重试有界、降级诚实 | 已覆盖 | — |
|
||
| 排雷循环 | 行动经济.md | AP 扣费、末点耗尽即收轮与战斗收束清零；停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励）；下轮行动点修正排队与兑现 | 已覆盖 | — |
|
||
| 表现与支撑 | HUD框架.md | 拒绝反馈分面可辨与未知兜底文案；结算明细带逐行呈现与排播节奏；模态覆盖层编排与输入锁；未开格类型微光（8 邻作用集／五组色相／零玩法写入）；UI 全局主题与按钮五态（含对比度锚）；中文字体随包与字形覆盖；地形瓦片套与格面数字可读；战斗叙述与终局文案（数值带入／胜负互异）；玩家面文案与危险格格面字形；战斗屏三区几何与棋盘格边长（分辨率两档×四档板型）；B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役）；模态句柄分域寻址面 | 已覆盖 | — |
|
||
| 表现与支撑 | 存档序列化.md | 存档写盘⇄读回往返保真；三槽位隔离与激活失败回滚；槽位摘要窥视与坏槽三态；启动态无激活不写盘；旧档迁移链与断点续玩零跳号（集成）；存档⇄RNG 快照往返保真（集成） | 已覆盖 | — |
|
||
| 表现与支撑 | 教学引导.md | — | 未覆盖 | 教学形态与首遇时机待设计；见待办清单「教学形态未定」条 |
|
||
| 表现与支撑 | 数据配置.md | 全表装载、就绪态与表清单目录对账；进度坐标查行：精确命中／向上取整／封顶／警告去重；运行期越域致命与进程非 0 退出；加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域；表结构守卫：域校验／行序键／跨字段互锁／配额锚 | 已覆盖 | — |
|
||
| 表现与支撑 | 设置与本地化.md | 减动效开关存储契约（持久化回读/缺省值/引擎动效档应用） | 已覆盖 | 存储契约三断言已落地；多语言切换面未建（P1，归设置与本地化待设计问题清单） |
|
||
| 表现与支撑 | 音频.md | — | 未覆盖 | MVP 无音频（P1 后置，无断言面）；见待办清单「能力清单覆盖缺口补齐」条 |
|
||
| 跨局循环 | 元进度.md | 元进度入账与锻造两轴 | 已覆盖 | — |
|
||
| 跨局循环 | 天赋树.md | 天赋树购买与六键合成 | 已覆盖 | — |
|
||
| 跨局循环 | 生涯.md | — | 未覆盖 | P6 后置未实装；见待办清单「「生涯」界面——冒险中数据回看的唯一承接处」条 |
|
||
| 跨局循环 | 秘宝.md | 秘宝结构冻结与 12 件效果；加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域 | 已覆盖 | — |
|
||
| 跨局循环 | 锻造工坊.md | 锻造表 schema 正反与几何价格梯；元进度入账与锻造两轴；锻造定价与购买闭环（全路线价格梯/多级购买扣款/拒购零副作用）；锻造与相邻通道隔离（祝福件购买锻造零变化/默认轴与钥匙解耦/甲型切换双轴可感） | 部分覆盖 | 六缺口（全路线价格梯／多级购买扣款／拒购零副作用／祝福件零泄漏／默认值解耦／甲型双轴）由「断言补齐批」承接；见待办清单「能力清单覆盖缺口补齐」条 |
|
||
|
||
## 断言计数双口径
|
||
|
||
断言计数不写死总数（写死必然漂移），取两种口径并注明语义：
|
||
|
||
- **运行时口径**：系统测试运行器（`tools/run_system_test.py`）打印的通过项数——循环内断言按执行次数计，随断言面增减浮动，以当次跑测打印为准。
|
||
- **静态口径**：断言面源码 `check(` 调用点计数——按源码位置计，一处在循环内即多次执行。
|
||
|
||
两口径数值不同且各自浮动，禁互相换算或写死。
|
||
|
||
## 工具速查（逐件：判什么 / 结果谁判 / 什么时候用）
|
||
|
||
| 工具 | 判什么 | 结果谁判 | 什么时候会用它 |
|
||
|---|---|---|---|
|
||
| `tools/run_smoke.py`（冒烟测试） | 这版能否启动、能否加载表、能否进主屏——零逻辑判定 | 退出码＋脚本错误扫描 | 开机路径／表加载改动后的快速自检；收口由闸编排 |
|
||
| `tools/run_system_test.py`（系统测试） | 真实玩法路径的行为断言面（推理→战斗→结算→进度推进） | 退出码＋脚本错误扫描 | 玩法链路改动的调试期确认 |
|
||
| `tests/run_all.gd`（单元与集成） | 公式／状态机／契约／跨系统闭环（65 套件 manifest） | 退出码＋三硬闸（见下）；每套件子进程带截止时间守护——超时先 taskkill /T 整树回收再判该套件 FAIL、批继续（默认 120s，环境变量 `RUN_ALL_SUITE_TIMEOUT_SEC` 可覆盖）；连续 3 个套件超时＝红树整批挂死，第 3 个即中止整轮、汇总已见失败与超时清单后非 0 退出（阈值＝可调常量，不连续的超时照旧逐个回收） | 新套件单跑调试；逻辑改动的最小单元复跑；开发期选跑——追加 `-- --only=<词[,词…]>` 只跑路径命中词的套件（零命中＝用法错 exit 2；此形态仅供开发期最窄确认，不产闸回执、不作验收凭据）；闸机关联档选跑——同一过滤机制加 `-- --only-source=gates`，由 `tools/run_all_gates.sh` 在 02 闸传入（回执 scope=related，是验收跑批本体） |
|
||
| `tools/probe_gate.sh`（场景探针，单一形态十件恒跑） | UI 可达性、可见性、状态——真实实例化场景＋真实输入路径 | 探针自检＋退出码 | 新增 UI 区域的配套探针直跑与断言复核 |
|
||
| `tools/render_gate.sh`（渲染 golden） | 画面基线——截图与基线图逐像素容差比对 | golden 比对脚本（依赖 PIL）＋退出码／取证双检／三段探针日志脚本错误扫描（`error_scan.py`） | 主题／素材／排版类改动；窗口化运行，需开显示器 |
|
||
| `game/tests/static_scan.sh`（S 域） | 项目纪律＋第三方质量规则：RNG 单点／core 纯度／类型标注／文件头／注释禁词／旧符号残留；S13＝gdstyle 质量规则（重复 load、循环内 await、循环内分配、不可达代码等真缺陷类；基线键＝文件|规则|函数名（类/文件级＝文件|规则，无数字条目带消息），数字漂移不假红，同键指标恶化超基线登记值即红） | 退出码（逐规则 FAIL 行） | 改产品码前后的快速自检；新增纪律先补扫描规则再修码 |
|
||
| 测量件（`game/sim/`，逐件见下「游离脚本台账」） | 期望／分布读数——只给读数，不判对错 | 人工读 stdout 或配套工具脚本 | 调参与归因；MC 类一律用户发起（档位表见 `sim-data/README.md`「MC 采集档位表」） |
|
||
|
||
> 单件直跑是调试期最窄确认手段，**不构成验收**——验收只有 `tools/run_all_gates.sh` 一个入口（判定三硬闸见下「本地闸」节）。
|
||
|
||
## Running Tests
|
||
|
||
```bash
|
||
# 冒烟测试——极小启动场景，秒级
|
||
python tools/run_smoke.py
|
||
|
||
# 单元与集成测试——Windows 须用 console 版 exe 取 stdout；工作目录 = game/（含 project.godot 那一层）
|
||
godot --headless --script tests/run_all.gd # 统一入口（本地单元与集成测试闸调用点）
|
||
godot --headless --script tests/run_all.gd -- --only=battle_settlement # 选跑态——只跑路径含该词的套件（开发期最窄确认；零命中＝用法错 exit 2，不产闸回执）
|
||
godot --headless --script tests/unit/example_test.gd
|
||
|
||
# 系统测试——过渡期宿主 smoke_all.gd；分钟级
|
||
python tools/run_system_test.py
|
||
|
||
# 场景探针（UI 探针层）——以探针场景为运行目标，走完整项目引导（autoload 在位）
|
||
godot --headless --path . res://probe/<probe>.tscn
|
||
|
||
# 挂死防护内建于 run_all.gd（引擎无死锁探测，超时靠外部判）：每套件子进程带截止时间——
|
||
# 默认 120s，环境变量 RUN_ALL_SUITE_TIMEOUT_SEC 可覆盖；超时先 taskkill /T 整树回收
|
||
#（cmd wrapper 连引擎孙进程一起杀，不留孤儿），该套件判 FAIL、批继续——单套件挂死不拖死整闸；
|
||
# 连续 3 个套件超时＝红树整批挂死，第 3 个即中止整轮（汇总已见失败与超时清单、退出码非 0），
|
||
# 不连续的超时照旧逐个回收；阈值是 run_all.gd 内可调常量
|
||
```
|
||
|
||
> 套件 manifest 现况：`_suites()` 登记 **65 条**（62 单元＋3 集成；口径＝manifest 条目数，
|
||
> 随套件增减浮动）——data_config（ConfigDB 加载/进度坐标 ceil 解析/fatal 退出码/统一随机流）、core（秘宝结构冻结/断点续玩/存档槽位/结算五段等）、battle_settlement（DamageMath 纯函数/DamageController 伤害单据五配方）、contracts（系统间接口契约断言）、presentation（节奏队列/奖励浮层/字体资产/地形瓦片集/模态编排等）；集成 3 条存 `tests/integration/`。致命类独立进程 `expect=1`；负面套件 `negative=true` 只豁免错误扫描一闸。期望值一律由表读值推导（零玩法数值字面量）、随机只经 RngService 统一流。
|
||
|
||
**协议要点**（D2 冒烟协议）：
|
||
- `--script` 载体 `extends SceneTree` 以获得 `quit(code)`；成功 `quit(0)`、失败 `quit(1)`
|
||
- `--script` 模式**不加载 autoload 且不注册全局标识符**（裸引用 `ConfigDB` = parse error）——ConfigDB/RngService 由脚本显式实例化，core 一律构造注入
|
||
- 冒烟测试走项目运行目标（场景拉起），autoload 全在位——与 `--script` 载体互补
|
||
- 致命类用例独立进程，runner manifest 登记"调用 → 期望退出码"
|
||
- 每用例先 `reset_diagnostics()`（诊断收集器协议）
|
||
- 期望值由表读值推导，不写死玩法数值
|
||
|
||
## Test Naming
|
||
|
||
- **Files**: `[system]_[feature]_test.gd`（领域命名，禁 ID 前缀——design/engineering/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 test pass | 跑批回执 `game/tests/.gates/receipt.json`（不入库）＋结论随批记 `reports/` |
|
||
|
||
## game/probe/ 游离脚本台账
|
||
|
||
`game/probe/` 里的脚本两分：**在闸件**（探针有 `.tscn` 宿主、被 `probe_gate.sh`／`render_gate.sh` 调用；
|
||
`smoke_all.gd` 被系统测试运行器调用——过渡期宿主）与**不入闸的手动测量/诊断件**（下表）。
|
||
判据 = 头注自陈用途 + 有无外部引用（工具脚本/产品码/文档）。**存疑一律按在役登记并标注**（不退役）。
|
||
|
||
| 脚本 | 定性 | 用途与触发方式 | 结果由谁判 |
|
||
|---|---|---|---|
|
||
| `adventure_monte_carlo.gd` | **在役**（`AGENTS.md` 在册入口） | 全冒险期望 MC | 人工读 stdout |
|
||
| `verifier_batch.gd` | **在役**（`AGENTS.md` 在册入口） | `tools/balance_verifier.py` 的采集端（数值验证） | 报告与原始数据落 `sim-data/` |
|
||
| `reward_expectation.gd` | **在役**（`AGENTS.md` 在册入口） | 奖励期望测量（非封锁格分布/资源类型频次） | 人工读 stdout |
|
||
| `monte_carlo.gd` | 在役 | 战斗期望 MC（胜轮数/承伤/清图/开格分布） | 人工读 stdout |
|
||
| `auto_player.gd` | 在役（库件） | 自动玩家策略单一实现——被 `battle_driver` preload | 宿主脚本 |
|
||
| `battle_driver.gd` | 在役（库件） | 战斗驱动；被 `damage_probe` preload | 宿主脚本 |
|
||
| `level_autoplay.gd` | 在役（库件） | 被 `presentation/tune_sim_controller.gd` load | 宿主脚本 |
|
||
| `probe_ui_util.gd` | 在役（库件） | 探针公共工具（存档隔离/句柄解析）——被各探针 preload | 宿主探针 |
|
||
| `board_stat_probe.gd` | 在役 | `tools/clear_dominance_audit.py` 的取数端 | 工具脚本 |
|
||
| `calibrate_boards.gd` | 在役 | 生成器真值分母；`sim-data/analyze.py` 引用 | 工具脚本 |
|
||
| `damage_probe.gd` | 在役（诊断件） | 零承伤根因分割探针（头注自陈：非验收件·不入闸） | 人工读 stdout |
|
||
| `defense_scan.gd` | 在役（诊断件） | AC 叠层减伤读数分割（高 AC 轮 vs 基线轮） | 人工读 stdout |
|
||
| `skill_rhythm_probe.gd` | 在役（分析工具） | 技能池节奏定位（表侧池快照 + 摇号份额） | 人工读 stdout |
|
||
| `rhythm_batch.gd` | 在役（批量采集） | 技能池节奏批量读数（06 在册项的机器半边） | 人工/工具 |
|
||
| `dump_battle.gd` | **在役·一次性** | 打印一场完整战斗的步骤流与棋盘摘要（肉眼验收归因质量） | 人工（用完即止） |
|
||
|
||
> **纪律**：本表是这些件的唯一在册处。新增手动测量脚本必须同批登记（用途 + 触发方式 + 结果由谁判）；
|
||
> 退役走 `design/engineering/doc-conventions.md` 第 10 节退役规则，禁止「没看见＝死件」式清理。
|
||
> 测量类批量的发起规则（档位与批准）见 `sim-data/README.md`「MC 采集档位表」——无数值改动禁重跑。
|
||
|
||
## Static Scan（提交前本地跑）
|
||
|
||
`tests/static_scan.sh` 实现静态扫描域 S1–S12 的可执行子集；S1–S10 的规则全集与动机见
|
||
`design/engineering/architecture/architecture.md`「测试与质量域」节，**S11／S12 两段的规则说明自持于本文件与
|
||
`tests/static_scan.sh` 头注**，这两段不另进架构文档。
|
||
新违规案例必须**先补扫描规则再修码**。
|
||
|
||
S11 代码注释禁用词：扫描 game/ 全域 .gd/.tres/.md/.json/.sh 的注释面；禁词全部由 `design/gdd/术语表.md`「退役词对照」第一列解析供给（脚本内不内联任何词面——单一事实源）；解析结果再按「巢穴」「旗」「flag_*」三条整行排除，另设同形异义豁免「去重闸」（封印重判去重的机制判别器，与某闸档退役词后二字同形——行内含「去重闸」整行跳过）；三层豁免（闸门自指／显式留档 20 处〔契约原名引述与带日期历史读数注释，清单见 `tests/static_scan.sh` 头注〕／非注释面天然不取）；两道自检（扫描面文件数非空＋词表解析非空）。
|
||
|
||
S12 效果引擎无状态化旧件零残留：扫描 game/ 全域 `.gd` 与 `game/data/tables/*.tres`，禁已删符号（`counters_export`／`counters_seed`／`_reset_tree_limited_counters` 等）与带引号的旧计数器 id 字面（引号锚定，不误伤 `adv_`／`round_` 前缀新名）；扫描面文件数为零即判红。
|
||
|
||
## 本地闸（唯一验收门禁）
|
||
|
||
**验收＝合回后远端 CI 闸全绿**（2026-11-03 用户裁，取代本地的合回验收；游戏码批＝两域全量、02 全套件）；`tools/run_all_gates.sh` 仍是全部验证闸的唯一入口与唯一清单，本地按改动域选档跑批（`--code`／`--docs`／跨两域或改闸件本身＝不带参数全量；代码域 02 按关联档选套件，回执 `scope` 字段记 full｜related）只服务开发期窄测，**不构成验收**，
|
||
跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `scope` 字段），合回 master 由 worktree-guard 按 diff 文件性质推域校验回执（`game/` 内 `.md` 归文档域）。
|
||
闸清单与域划分（含选闸算法与套件族映射表）的唯一定义处就是那个脚本，本文档不另列清单（清单散落多份文档正是历史漏跑闸的成因）。
|
||
|
||
**判定三硬闸**（各闸一律适用，缺一即判定有洞）：
|
||
①**退出码为唯一权威判据**——日志里的 PASS 串只是日志，不作判据；
|
||
②**脚本错误扫描命中即红**——GDScript 的 `SCRIPT ERROR` / `Parse Error` 不改进程退出码、
|
||
不计失败数，且会静默中断所在函数的剩余断言，只能由外部扫输出（闸件 `tools/error_scan.py`，
|
||
错误标记与 `tools/run_smoke.py` 同源）；
|
||
③**断言数为零即红**——`test_kit.gd` 的 `finish()` 在零断言时返回专用退出码 2（与「断言失败=1」
|
||
区分，避免致命类套件的 expect 协议把它当成预期结果放过）。
|
||
|
||
**gdUnit4 维持 deferred**：不引入第三方测试框架，本仓库在既有载体（`--script` 套件＋场景运行目标）内解决。
|
||
|
||
## 闸门耗时基线（超时对比依据）
|
||
|
||
各闸在本机（Windows 基准档）的预期耗时区间与耗时模型。单次跑批实测显著超出区间上限（约 2× 中值）时，先核对环境因素（导入缓存重建、杀毒扫描、显示器休眠）再判性能回归。区间为单机粗测值；闸回执后续若记录实际耗时，以其积累值替换本表。
|
||
|
||
| 闸 | 耗时模型 | 预期区间 | 备注 |
|
||
|---|---|---|---|
|
||
| 00 冒烟 | O(1)——引擎启动一次＋存活检查 | ~10–20 秒 | |
|
||
| 01 系统测试 | O(屏壳装配数 × 断言面规模) | ~2–3 分钟 | 断言计数随面浮动（口径见「断言计数双口径」节） |
|
||
| 02 单元与集成 | O(套件 manifest 条目数 × 单套件冷启动) | ~3–6 分钟 | 每套件独立子进程；单套件挂死守卫 120 秒 |
|
||
| 03 场景探针 | O(探针段数 × 引擎冷启动) | ~3–5 分钟（--full／--click 各计一次） | 耗时大头＝每段一次引擎冷启动 |
|
||
| 05 渲染 | O(截图段数 × 窗口化冷启动 ＋ golden 比对) | ~8–15 分钟 | 五段串行，需显示器在位 |
|
||
| 远端 CI 全量 | 上列各闸串联（两域全量） | ~30–35 分钟 | 2026-11-04 远端 run 实测 ≈33 分钟（单点样本） |
|
||
|
||
## 术语（本项目内的唯一语义）
|
||
|
||
标准四级测试层（2026-10-22 用户裁，权威对照=design/gdd/术语表.md「退役词对照」）：
|
||
|
||
| 词 | 语义 | 载体 |
|
||
|---|---|---|
|
||
| **冒烟测试** | 秒级存活检查——能否启动、能否加载表、能否进主屏。判断「这版还活着吗」，不判断「这版对不对」 | `tests/smoke_boot.tscn/.gd`、`tools/run_smoke.py` |
|
||
| **单元测试** | 隔离的公式/状态机/纯逻辑断言面，逐套件独立进程实跑 | `game/tests/unit/`、`run_all.gd` |
|
||
| **集成测试** | 跨系统闭环断言面（存档⇄RNG 往返、回放确定性等） | `game/tests/integration/`、`run_all.gd` |
|
||
| **系统测试** | 启动真实工程走真实玩法路径的断言面 | 过渡期 `game/probe/smoke_all.gd`＋`tools/run_system_test.py`；迁移后 `tests/system_test.gd` |
|
||
| **场景探针** | 以探针场景为运行目标、走完整项目引导（autoload 在位）的 UI/场景断言 | `game/probe/*.tscn`、`probe_gate.sh` |
|
||
| **渲染 golden** | 窗口化截图与基线图的逐像素容差比对 | `render_gate.sh`、`tests/golden/` |
|