游戏引擎 / 系统课时
场景树回归测试验证架构边界
场景树回归测试验证架构边界
本课把场景复用的约束变成一份无需打开游戏窗口的自动化检查:验证同一模板能独立实例化、节点换父级后位置稳定、运行状态互不污染,以及切换关卡后旧场景真正释放。脚本会逐项报告成功或失败,并用退出码让重构和持续集成及时发现回归。
学习目标
- 用
SceneTree脚本建立可重复执行的无窗口测试入口。 - 检查实例、节点层级、运行状态和切关生命周期四类边界。
- 故意引入共享状态错误,验证测试能输出失败并返回非零退出码。
明确需要守住的边界
测试使用运行时构造的 PackedScene,避免依赖游戏素材。模板包含根节点和 Health 子节点;只有给子节点设置正确的 owner,打包后才能在新实例中找到它。
同一模板实例化为 A、B 后,分别为它们创建运行状态字典。接着将 A 从左侧父节点重挂到右侧父节点,验证 global_position 不变。最后通过 change_scene_to_packed() 切换 LevelA 和 LevelB,在 scene_changed 后检查旧关卡已失效。

编写无窗口测试入口
在 Godot 4.6 工程下新建 res://tests/scene_tree_regression.gd。脚本继承 SceneTree,利用延迟调用启动测试,确保运行时场景树已经初始化。这里使用显式的 _check() 而不是单靠 assert():它能继续汇总其他检查,并在失败时以退出码 1 结束。
extends SceneTree
const BREAK_STATE_ISOLATION := false
var failure_count := 0
func _init() -> void:
call_deferred("_run")
func _check(ok: bool, label: String) -> void:
if ok:
print("PASS: " + label)
else:
failure_count += 1
printerr("FAIL: " + label)
func _make_scene(scene_name: String) -> PackedScene:
var template := Node2D.new()
template.name = scene_name
var health := Node.new()
health.name = "Health"
template.add_child(health)
health.owner = template # owner 决定打包时是否包含子节点
var packed := PackedScene.new()
var err := packed.pack(template)
template.free()
_check(err == OK, "打包 " + scene_name)
return packed
func _run() -> void:
var unit_scene := _make_scene("Unit")
if not unit_scene.can_instantiate():
quit(1)
return
var left := Node2D.new()
var right := Node2D.new()
left.position = Vector2(100, 0)
right.position = Vector2(300, 0)
root.add_child(left)
root.add_child(right)
var a := unit_scene.instantiate() as Node2D
var b := unit_scene.instantiate() as Node2D
a.name = "A"
b.name = "B"
left.add_child(a)
left.add_child(b)
_check(a != b and a.has_node("Health") and b.has_node("Health"),
"独立实例化")
var defaults := {"hp": 100}
var a_state := defaults.duplicate(true)
var b_state := defaults.duplicate(true)
if BREAK_STATE_ISOLATION:
b_state = a_state # 故障注入:误用同一个状态字典
a.get_node("Health").set_meta("state", a_state)
b.get_node("Health").set_meta("state", b_state)
a_state["hp"] = 40
var b_actual: Dictionary = b.get_node("Health").get_meta("state")
_check(b_actual["hp"] == 100, "实例状态隔离")
a.position = Vector2(20, 5)
var before := a.global_position
a.reparent(right, true)
_check(a.get_parent() == right and a.global_position.is_equal_approx(before),
"重挂父级保持世界位置")
left.free()
right.free()
var level_a := _make_scene("LevelA")
var level_b := _make_scene("LevelB")
if not level_a.can_instantiate() or not level_b.can_instantiate():
quit(1)
return
var start_err := change_scene_to_packed(level_a)
_check(start_err == OK, "加载关卡 A")
if start_err != OK:
quit(1)
return
await scene_changed
var old_level := current_scene
_check(old_level != null and old_level.name == "LevelA", "关卡 A 就绪")
var switch_err := change_scene_to_packed(level_b)
_check(switch_err == OK, "切换到关卡 B")
if switch_err != OK:
quit(1)
return
_check(current_scene == null, "切关间隙没有当前关卡")
await scene_changed
_check(current_scene != null and current_scene.name == "LevelB",
"关卡 B 就绪")
_check(not is_instance_valid(old_level), "旧关卡已释放")
if failure_count == 0:
print("ALL PASS")
else:
printerr("FAILED: %d" % failure_count)
quit(0 if failure_count == 0 else 1)预期结果:脚本具备完整的测试入口;成功时会打印各项 PASS 和 ALL PASS,失败时会打印 FAIL 并返回退出码 1。具体运行日志见下节。
运行并核对结果
确认工程根目录存在 project.godot,且 godot 命令指向 Godot 4.6 可执行程序。在工程根目录运行:
godot --headless --path . --script res://tests/scene_tree_regression.gd预期输出(省略引擎版本横幅):
PASS: 打包 Unit
PASS: 独立实例化
PASS: 实例状态隔离
PASS: 重挂父级保持世界位置
PASS: 打包 LevelA
PASS: 打包 LevelB
PASS: 加载关卡 A
PASS: 关卡 A 就绪
PASS: 切换到关卡 B
PASS: 切关间隙没有当前关卡
PASS: 关卡 B 就绪
PASS: 旧关卡已释放
ALL PASS进程正常以退出码 0 结束。scene_changed 表示新关卡已加入场景树并完成初始化;切换请求刚发出时不能直接假定 current_scene 已指向新关卡。
故意制造一次回归
将脚本顶部的 BREAK_STATE_ISOLATION 改为 true,其他内容不变,重新执行同一命令。此时 B 的运行状态会错误地引用 A 的字典;修改 A 的生命值也将改变 B。预期失败信息包含:
FAIL: 实例状态隔离
FAILED: 1其他测试仍可通过,进程应以退出码 1 结束。把常量恢复为 false 再运行,应重新出现 ALL PASS。这一步证明检查不是无条件放行,也让自动化流水线能区分成功与失败。
将夹具替换成真实场景
上面的运行时模板是最小测试夹具,它验证测试机制,但不能直接证明项目里的角色场景没有回归。接入项目时,应把 unit_scene 的初始化改为通过 load() 读取项目实际的 res:// 角色场景资源,改用实际状态组件及节点路径,并用真实关卡资源替换 LevelA、LevelB。
保留四项可观察约束:新实例不共享可变状态;重挂后父子关系正确且空间变换符合预期;关卡切换必须等待 scene_changed;旧场景引用最终不再有效。需要跨场景保留的 Autoload 和常驻 HUD 应单独断言其仍然存在,不能误认为它们也该随关卡销毁。此测试适用于每次调整场景层级、资源归属或切关流程后的快速回归;画面渲染和物理碰撞仍须由相应测试覆盖。