godot-testing

Godot Testing

Overview

Godot has two mature test frameworks: gdUnit4 (GDScript and C#, fluent assertions, scene runner, mocks) and GUT (GDScript, simple assertions, doubles). Use the one in addons/; if neither exists, add gdUnit4. Test plain typed classes directly; use a scene runner only for behaviour that needs frames, physics, input or the tree.

Core principle: Unit-test the class, scene-test the wiring, and run it headless with an exit code you read.

gdUnit4

# res://test/combat/health_component_test.gd
class_name HealthComponentTest extends GdUnitTestSuite

func test_damage_beyond_health_clamps_to_zero() -> void:
    var health: HealthComponent = auto_free(HealthComponent.new())
    health.max_health = 50
    health.reset()

    health.damage(80)

    assert_int(health.current).is_equal(0)

func test_lethal_damage_emits_died() -> void:
    var health: HealthComponent = auto_free(HealthComponent.new())
    health.max_health = 10
    health.reset()
    monitor_signals(health)          # start collecting before the action, or an already-emitted signal is missed
    health.damage(10)
    await assert_signal(health).is_emitted("died")

func test_player_falls_onto_floor_and_is_grounded() -> void:
    var runner := scene_runner("res://test/scenes/flat_floor_with_player.tscn")
    await runner.simulate_frames(90)
    var player := runner.find_child("Player") as Player
    assert_bool(player.is_on_floor()).is_true()

func test_jump_action_leaves_the_ground() -> void:
    var runner := scene_runner("res://test/scenes/flat_floor_with_player.tscn")
    await runner.simulate_frames(30)
    runner.simulate_action_pressed("jump")
    await runner.simulate_frames(5)
    assert_float((runner.find_child("Player") as Player).velocity.y).is_less(0.0)

• auto_free() frees the object after the test; nodes added to the tree go through the runner or add_child(auto_free(node)).
• mock(Class) / spy(instance) with verify(...) exist — prefer real collaborators and fakes; assert outcomes, not calls.
• Parameterised tests: a default argument test_parameters := [[...], [...]].