Index of every page on this site: llms.txt
All skills
jame581 avatar

/godot-testing

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when writing tests for Godot projects — TDD workflow with GUT and gdUnit4, covers both GDScript and C#

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/godot-testing

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencestesting-patterns.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Testing Patterns

Reference for skills/godot-testing/SKILL.md — testing scenes with nodes, signal testing, mocking/doubling, awaiting async operations.

← Back to SKILL.md


Testing Patterns

Scenes with Nodes

Always use add_child_autofree (GUT) or auto_free (gdUnit4) so nodes are freed after each test. Never call queue_free() manually inside tests — it causes race conditions.

GUT
func before_each() -> void:
    # add_child_autofree: adds to scene tree AND frees after test
    var scene := preload("res://scenes/player.tscn")
    _player = add_child_autofree(scene.instantiate())

    # autofree: frees after test but does NOT add to scene tree
    _resource = autofree(MyResource.new())
gdUnit4 (GDScript)
func before_test() -> void:
    var scene := preload("res://scenes/player.tscn")
    _player = auto_free(scene.instantiate())
    add_child(_player)
gdUnit4 (C#)
[BeforeTest]
public void BeforeTest()
{
    var scene = GD.Load<PackedScene>("res://scenes/player.tscn");
    _player = AutoFree(scene.Instantiate<Player>());
    ((SceneTree)Engine.GetMainLoop()).Root.AddChild(_player); // suites are not Nodes
}

Signal Testing

GUT
func test_health_emits_signal() -> void:
    watch_signals(_health)
    _health.take_damage(10)

    # Assert signal was emitted
    assert_signal_emitted(_health, "health_changed")

    # Assert signal was emitted with specific arguments
    assert_signal_emitted_with_parameters(_health, "health_changed", [100, 90])

    # Assert signal was NOT emitted
    assert_signal_not_emitted(_health, "died")
gdUnit4 (GDScript)
func test_health_emits_signal() -> void:
    var monitor := monitor_signals(_health)
    _health.take_damage(10)

    # is_emitted() waits for the signal, so it must be awaited.
    await assert_signal(monitor).is_emitted("health_changed")
    await assert_signal(monitor).is_emitted("health_changed", [100, 90])
    await assert_signal(monitor).is_not_emitted("died")
gdUnit4 (C#)
[TestCase]
public async Task HealthEmitsSignal()
{
    AssertSignal(_health).StartMonitoring();
    _health.TakeDamage(10);

    await AssertSignal(_health).IsEmitted(HealthComponent.SignalName.HealthChanged).WithTimeout(100);
    await AssertSignal(_health).IsEmitted(HealthComponent.SignalName.HealthChanged, 100, 90).WithTimeout(100);
    await AssertSignal(_health).IsNotEmitted(HealthComponent.SignalName.Died).WithTimeout(100);
}

Mocking / Doubling

Use doubles/mocks to isolate the unit under test from dependencies.

GUT — double() and stub()
func test_player_uses_health_component() -> void:
    # double() returns a doubled class; .new() makes the instance.
    # Methods of a full double do nothing and return null.
    var mock_health = double(HealthComponent).new()
    stub(mock_health, "take_damage")  # no-op stub
    # Only methods can be stubbed — current_health is a property.

    _player.health_component = mock_health
    _player.take_hit(25)

    # Verify the method was called
    assert_called(mock_health, "take_damage")
    assert_called(mock_health, "take_damage", [25])  # with these arguments
gdUnit4 (GDScript) — mock()
func test_player_uses_health_component() -> void:
    var mock_health = mock(HealthComponent)
    # do_return(x).on(mock).method() stubs methods only — current_health is a property.

    _player.health_component = mock_health
    _player.take_hit(25)

    verify(mock_health).take_damage(25)
gdUnit4 (C#) — hand-rolled fake

gdUnit4Net has no mock(), spy() or verify(); those are GDScript-only. Subclass the dependency (its methods must be virtual) or inject an interface:

public partial class FakeHealth : HealthComponent
{
    public int LastDamage { get; private set; } = -1;
    public override void TakeDamage(int amount) => LastDamage = amount;
}

[TestCase]
public void PlayerUsesHealthComponent()
{
    var fakeHealth = AutoFree(new FakeHealth());

    _player.HealthComponent = fakeHealth;
    _player.TakeHit(25);

    AssertThat(fakeHealth.LastDamage).IsEqual(25);
}

Waiting for Async Operations

GUT
func test_tween_completes() -> void:
    _player.start_move_tween()

    # Wait a fixed duration
    await wait_seconds(0.5)
    assert_eq(_player.position, Vector2(100, 0))

    # Wait a number of frames
    await wait_frames(10)
    assert_true(_player.tween_finished)
gdUnit4 (GDScript)
func test_tween_completes() -> void:
    _player.start_move_tween()
    await await_millis(500)
    assert_that(_player.position).is_equal(Vector2(100, 0))
gdUnit4 (C#)
[TestCase(Timeout = 1000)]
public async Task TweenCompletes()
{
    _player.StartMoveTween();
    await _player.ToSignal(_player.GetTree().CreateTimer(0.5), SceneTreeTimer.SignalName.Timeout);
    AssertThat(_player.Position).IsEqual(new Vector2(100, 0));
}

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning8d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    This skill provides comprehensive instructions and code examples for implementing test-driven development in Godot projects using GUT and gdUnit4 frameworks. It includes legitimate commands for installing official tools and running tests locally and in CI environments.

  • Socket8d

    No alerts

  • Snyk8d

    Risk: MEDIUM · 1 issue

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last month

README badge

README badge for jame581/godotprompter/godot-testing