Community编程与开发github.com

godot-testing-debug

测试和调试 Godot 4.7 项目——支持 GdUnit4 (GDScript) 和 gdUnit4Net (C#) 已验证版本,涵盖单元测试、场景运行器测试、模拟、信号断言、输入模拟、无头运行输出 JSON、调试器、断点、自定义 Logger、回溯以及错误读取。适用于编写或运行测试、追踪 Bug 和崩溃。

godot-testing-debug 是什么?

该技能为 Godot 4.7 项目提供全面的测试与调试能力,支持 GDScript(GdUnit4 6.2.2)和 C#(gdUnit4Net 5.1.0-rc5)两种语言。测试框架支持单元测试、场景运行器集成测试、模拟(mock/spy)、信号断言、输入模拟以及无头运行,并以 JSON 格式输出结果。调试功能包括编辑器内置调试器(断点、单步执行、远程场景树)、自定义 Logger 用于应用内 Bug 报告、CLI 调试参数以及 C# IDE 附加调试。文档还提供了快速解析常见错误信息(如空实例、提前释放、未进入场景树)的指导,帮助开发者高效定位和修复问题。适用于 Claude Code、Cursor、Codex 等 AI 代理,在编写或运行测试、追踪 Bug 和崩溃时发挥作用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EL4CTEO/godot-skills/tree/main/skills/godot-testing-debug

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

测试与调试 (4.7)

运行测试: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] 返回 {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}}。该脚本先进行导入,然后无头运行,并解析 JUnit/控制台结果。 运行测试前,需编译:../godot-gdscript/scripts/gd_check.py 和 ../godot-csharp/scripts/cs_build.py。使用 ../godot-core/scripts/run_godot.py smoke 对游戏进行冒烟测试。

GDScript:GdUnit4(已验证 4.7.2 上的 6.2.2)

  • 安装:从 GitHub 发布版(github.com/godot-gdunit-labs/gdUnit4,标签 v6.2.x)复制 addons/gdUnit4 并启用插件。测试文件放在 res://test/ 中,文件名以 _test.gd 结尾。
  • 测试套件 extends GdUnitTestSuite。测试方法是 func test_*()。钩子函数:before()、after()(每个套件)、before_test()、after_test()。
  • 断言:assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...)、assert_that(x)、assert_signal(obj).is_emitted("died")(需先调用 monitor_signals(obj))、assert_error(func() -> void: ...) 以及 await assert_func(obj, "is_ready").is_true()。
  • 内存管理:将创建的对象包裹在 auto_free(...) 中。报告会标记孤儿节点,应将其视为 Bug。
  • 模拟:mock(Class) + do_return(v).on(m).method()、spy(instance)、verify(m, times).method(args)、any_int() 及相关方法。
  • 集成测试:var runner := scene_runner("res://player.tscn"),然后使用 runner.simulate_action_pressed("jump")、await runner.simulate_frames(30)、runner.simulate_key_pressed(KEY_SPACE)、await runner.await_signal("landed")、runner.invoke("method") 和 runner.scene()。
  • CLI(test_run.py 调用方式):godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test。退出码 0 表示通过,100 表示有失败。报告为 JUnit XML 格式,存放在 -rd 参数指定的目录下。

C#:gdUnit4Net(已验证 Godot.NET.Sdk 4.7.2,.NET 10 SDK)

  • 在游戏项目的 csproj 中添加:Microsoft.NET.Test.Sdk 18.x、gdUnit4.api 5.1.0-rc5(适配器 3.1.1 要求 ≥5.1.0-rc5;5.0.0 因 NU1605 无法还原)、gdUnit4.test.adapter 3.1.1、gdUnit4.analyzers 1.0.0,以及 <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>。
  • 添加 .runsettings 文件,内容包含 <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>。不添加此文件会导致 Godot 运行时测试因连接超时而失败。使用 GODOT_BIN=<godot 可执行文件> dotnet test --settings .runsettings 运行。
  • [TestSuite] 类、[TestCase] 方法、[Before]/[After]/[BeforeTest]/[AfterTest]、参数化测试使用 [DataPoint(nameof(Cases))]。使用 using static GdUnit4.Assertions; 后即可调用 AssertThat(x).IsEqual(y)、AutoFree(node)。
  • [RequireGodotRuntime] 必须添加到任何涉及 Godot 类型(包括 Mathf、节点和资源)的测试上。否则分析器会报告 GdUnit0501。纯 C# 测试无需引擎即可运行,速度更快。
  • 场景:ISceneRunner.Load("res://x.tscn") → SimulateFrames、SimulateActionPressed、AwaitSignal、Invoke。

测试内容

纯逻辑(伤害、背包、存档迁移)应编写快速的单元测试。场景通过场景运行器测试控制器手感、UI 流程和信号连接。每个 Bug 修复都要添加回归测试。保持测试套件快速执行,因为慢的套件会逐渐无人运行。

调试

  • 从编辑器运行(F5)可使用完整调试器:错误附带堆栈跟踪、断点(或 breakpoint 语句)、单步进入/跳出(4.6 版新增 Step Out)、远程场景树(运行时可实时检查节点和属性)、性能分析器、监视器和 ObjectDB 快照(4.6)。
  • 日志:print、print_rich("[color=yellow]...")、print_debug(添加文件和行号)、push_warning/push_error(在调试器中显示并附有堆栈,非致命)、printerr。assert(cond, "msg") 仅在调试版本中运行,因此切勿在其中放置副作用。
  • 文件日志:debug/file_logging/enable_file_logging(桌面版默认开启,日志文件为 user://logs/godot.log)。可通过 OS.get_user_data_dir() 找到 user://。
  • 自定义 Logger(4.5+): 继承该类,重写 _log_error/_log_message,并使用 OS.add_logger() 注册。可用于应用内错误报告,配合 script_backtraces 使用。在发布版本中启用 debug/settings/gdscript/always_track_call_stacks 以获取回溯信息。Engine.capture_script_backtraces() 可按需捕获回溯。
  • CLI:-d(标准输出调试器)、--verbose、--debug-collisions/--debug-navigation、以及 --remote-debug tcp://host:6007 将运行中的构建附加到编辑器。
  • C#:将 IDE 调试器附加到游戏进程(Rider 和 VS Code C# Dev Kit 可以使用 --path 启动 Godot)。异常会被记录日志,而非致命,请留意输出面板。

快速阅读错误

res://file.gd:LINE 指明了错误所在行。"null instance" 表示节点路径错误或在 _ready 之前使用了某些内容。"previously freed" 表示 await 或回调的生命周期超过了其所属节点。"Parse Error" 或 "Compile Error" 会阻止脚本加载,导致所有使用该脚本的内容失败,因此应首先修复第一个错误。"Condition "!is_inside_tree()" is true" 表示在尚未加入场景树的节点上调用了树相关 API。引擎 C++ 文件引用(scene/main/node.cpp:123)仍然意味着你的调用有问题,请仔细阅读堆栈。

GdUnit 测试套件(单元测试、模拟、信号、场景运行器)、C# 测试、游戏内 Logger(由测试编译):references/patterns.md

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能