游戏引擎 / 系统课时

场景树回归测试验证架构边界

场景树回归测试验证架构边界

本课把场景复用的约束变成一份无需打开游戏窗口的自动化检查:验证同一模板能独立实例化、节点换父级后位置稳定、运行状态互不污染,以及切换关卡后旧场景真正释放。脚本会逐项报告成功或失败,并用退出码让重构和持续集成及时发现回归。

学习目标

  • 用 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 结束。

gdscript
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 可执行程序。在工程根目录运行:

bash
godot --headless --path . --script res://tests/scene_tree_regression.gd

预期输出(省略引擎版本横幅):

text
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。预期失败信息包含:

text
FAIL: 实例状态隔离
FAILED: 1

其他测试仍可通过,进程应以退出码 1 结束。把常量恢复为 false 再运行,应重新出现 ALL PASS。这一步证明检查不是无条件放行,也让自动化流水线能区分成功与失败。

将夹具替换成真实场景

上面的运行时模板是最小测试夹具,它验证测试机制,但不能直接证明项目里的角色场景没有回归。接入项目时,应把 unit_scene 的初始化改为通过 load() 读取项目实际的 res:// 角色场景资源,改用实际状态组件及节点路径,并用真实关卡资源替换 LevelA、LevelB。

保留四项可观察约束:新实例不共享可变状态;重挂后父子关系正确且空间变换符合预期;关卡切换必须等待 scene_changed;旧场景引用最终不再有效。需要跨场景保留的 Autoload 和常驻 HUD 应单独断言其仍然存在,不能误认为它们也该随关卡销毁。此测试适用于每次调整场景层级、资源归属或切关流程后的快速回归;画面渲染和物理碰撞仍须由相应测试覆盖。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

场景树回归测试验证架构边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通