测试与调试 (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.Sdk18.x、gdUnit4.api5.1.0-rc5(适配器 3.1.1 要求 ≥5.1.0-rc5;5.0.0 因 NU1605 无法还原)、gdUnit4.test.adapter3.1.1、gdUnit4.analyzers1.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