godot-testing-patterns

决策树 → 脚本

需求	选择	脚本（选用时必须使用）
纯逻辑 / 无场景树	单元测试	basic_unit_test.gd、mock_dependency_test.gd、test_data_factory.gd
实例化后的节点交互	场景集成测试	scene_integration_test.gd、integration_test_base.gd
信号契约	单元测试或场景测试	signal_emission_test.gd
多帧 / 物理步进	异步场景测试	wait_for_frame_test.gd、physics_collision_test.gd
不稳定的物理行为 / 时序竞争	帧步进门控	必须使用 wait_for_frame_test.gd — 切勿使用墙上时钟休眠
CI / 无显示设备	无头模式门控	必须使用 headless_test_runner.gd
存档 / UI 回归	快照	必须使用 snapshot_tester.gd
无实时对等端的 RPC	模拟网络	必须使用 mock_network_provider.gd
CI 中的性能预算	基准测试门控	performance_benchmark_runner.gd
套件运行后的孤立节点	泄漏检测	memory_leak_detector.gd
边界输入空间	模糊测试	parameter_fuzz_tester.gd

切勿加载断言目录教程或手动游戏检查清单到上下文中 — 选择一行，阅读脚本并实现。

必须遵循的触发条件

• CI / --headless：始终先阅读 headless_test_runner.gd（OS.exit_code，GdUnit4 CLI：godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://test）。
• 状态或视觉黄金文件：编写 JSON / 图像黄金文件前先阅读 snapshot_tester.gd。**批准工作流：**首次运行时保存参考；UI 有意更改时 → 删除或覆盖 res://tests/snapshots/<name>.png，重新运行以生成新文件，并提交新的黄金文件；切勿手动编辑 PNG 字节。
• 任何 RPC / MultiplayerSynchronizer 测试：启动真实对等端前先阅读 mock_network_provider.gd。

可用脚本

basic_unit_test.gd

适用于纯逻辑的最小 GdUnit4（GdUnitTestSuite）结构。

signal_emission_test.gd

用于解耦架构的信号发射监控。

mock_dependency_test.gd

使用模拟对象 / 测试替身隔离外部服务。

scene_integration_test.gd / integration_test_base.gd

场景生命周期与节点交互的测试夹具。

headless_test_runner.gd

CI 无头模式编排和退出代码。

snapshot_tester.gd

字典 / UI 黄金快照比较。

mock_network_provider.gd

用于 RPC 测试的环回 / 离线多人游戏对等端。

performance_benchmark_runner.gd

微秒计时器与 Performance 监控门控。

memory_leak_detector.gd

在长时间运行的测试套件中检测孤立节点。

parameter_fuzz_tester.gd

用于边界崩溃测试的随机化范围。

wait_for_frame_test.gd / physics_collision_test.gd

帧 / 物理步进异步验证。

test_data_factory.gd

符合架构定义的测试夹具构建器。

GdUnit4 测试中绝对不要做的事

• 绝对不要测试私有实现细节——只断言公开行为。
• 绝对不要在测试之间共享可变状态——每个测试都要重新设置（before_test / 等效方式）。
• 绝对不要使用墙上时钟 sleep / 盲目计时器——优先使用 wait_for_frame 模式中的帧步进器。
• 绝对不要跳过清理——每个测试后释放实例化的节点。
• 绝对不要在未设定种子的情况下测试随机性。
• 绝对不要在未使用 GdUnit 信号断言/监视辅助工具的情况下断言信号，这些工具见 signal_emission_test.gd。
• 绝对不要在同一个测试套件中混用 GUT 和 GdUnit4 API。
• 绝对不要依赖仅限编辑器的功能进行 CI——测试必须兼容无头模式。
• 绝对不要默认进行完整关卡集成测试——优先选择单元测试和小型场景测试；仅在决策树指出需要时才升级。
• 绝对不要在测试夹具中硬编码脆弱的绝对文件路径。
• 绝对不要测试第三方插件内部实现——只测试你的集成。

专家关卡（简版）

• 快照：序列化 → 与黄金样本比较（snapshot_tester.gd）；经批准的视觉变更后重新生成参考 PNG。
• CI：使用 --headless + 失败时 OS.exit_code 为非零值（headless_test_runner.gd）。
• 网络：先使用模拟对等端，再使用真实 ENet（mock_network_provider.gd）。
• 性能：在基准测试运行器中使用 Performance 监视器 / 绘制调用上限。

深入方案（按需查阅）

LLM 无知规则：如果通用 Agent 在阅读前不会知道某项内容，就将其放在这里或 scripts/ 中——绝不要删除，只能移动。

主题	参考资料
快照 / CI / 模糊测试 / 性能	expert-testing-patterns.md
发布冒烟测试清单	manual-testing-checklist.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到相关领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 命令行教程 — --headless、-s 以及适用于 CI 测试运行器的退出代码模式。
• 调试工具概览 — 当失败的测试需要引擎端诊断时，可使用调试器、性能分析器和远程检查。
• 自定义性能监视器 — 用于基准测试门槛和孤立对象检测的 Performance 监视器与自定义指标。
• 空闲处理与物理处理 — 帧与 _physics_process 的时序是 wait_frames / yield 辅助函数必须遵循的规则。
• 使用 SceneTree — 无头协调器使用的树生命周期、quit() 和处理模式。
• 节点与场景实例 — 场景集成测试中的 instantiate/add_child/free 管理规范。
• 通过信号实例化 — 信号触发测试所验证的信号连接模式。
• 高级多人游戏 — 通过 OfflineMultiplayerPeer 或延迟模拟器模拟的 RPC/peer API。
• 使用 InputEvent — 用于模糊测试和 UI 交互测试的合成 InputEvent* 注入。
• 随机数生成 — 为确定性模糊测试和蒙特卡洛测试框架设定种子。
• 保存游戏 — 用于黄金 JSON 和存档/读档集成测试的序列化/反序列化模式。
• 物理学简介 — 碰撞集成测试中的层/遮罩与步进时序。

相关技能

前置条件

• godot-project-foundations — 在搭建 res://test/ 测试套件前，了解项目布局、场景和资源。
• godot-gdscript-mastery — 每个单元测试/集成测试都会用到的类型化 GDScript、await 和断言惯用法。
• godot-signal-architecture — watch_signals / 信号监视器所断言的发出/连接约定。

补充

• godot-debugging-profiling — 当失败的测试需要运行时证据，而不是再加一条断言时，使用性能分析器和 ObjectDB 工具。
• godot-scene-management — 场景打包／加载模式在场景集成测试夹具中的对应实现。
• godot-input-handling — 模糊测试和 UI 按键测试所覆盖的动作映射和事件解析。
• godot-2d-physics — 物理碰撞测试必须确保通过的层级矩阵和物体 API。
• godot-resource-data-patterns — 测试数据工厂和快照字典序列化所用的 Resource 模式。
• godot-save-load-systems — 由存档／加载集成测试和黄金状态测试覆盖的持久化管线。

下游／使用方

• godot-monte-carlo-balancer — 使用这些测试框架进行带种子的无头游戏模拟，生成第 7 阶段的黄金数据单元。
• godot-performance-optimization — CI 性能门禁强制执行的预算（Performance 监视器、绘制调用上限）。
• godot-multiplayer-networking — 通过模拟对等端和延迟注入验证 RPC／复制逻辑。
• godot-export-builds — 调用相同 --headless 测试入口的无头导出／CI 管线。

主模块

• godot-master — 用于跨技能发现的库路由器和对应模块入口。