Testing with Dependency Injection
Reference for skills/dependency-injection/SKILL.md — testing nodes in isolation by injecting test doubles. Uses GUT for GDScript.
← Back to SKILL.md
7. Testing with Dependency Injection
Injectable dependencies make tests trivial: swap the real service for a stub or mock. Because the node declares what it needs (via @export or a property), tests can provide a controlled stand-in without touching autoloads.
GDScript (using GUT)
# stub_audio.gd — a lightweight stand-in for the AudioManager autoload.
# It must extend AudioService (the script that declares class_name AudioService,
# registered as autoload "AudioManager") to fit the typed `@export var audio: AudioService`;
# a plain Node is rejected. The class_name cannot be AudioManager: that hides the autoload.
class_name StubAudio
extends AudioService
var last_sfx: String = ""
var play_count: int = 0
func _ready() -> void:
pass # skip loading the real sfx library
func play_sfx(key: String) -> void:
last_sfx = key
play_count += 1# test_health_component.gd
extends GutTest
var health: HealthComponent
var audio_stub: StubAudio
func before_each() -> void:
audio_stub = StubAudio.new()
add_child_autofree(audio_stub)
health = preload("res://components/health_component.tscn").instantiate()
health.audio = audio_stub # inject the stub — no real AudioManager needed
health.max_health = 100
add_child_autofree(health)
func test_take_damage_plays_hurt_sfx() -> void:
health.take_damage(10)
assert_eq(audio_stub.last_sfx, "hurt")
assert_eq(audio_stub.play_count, 1)
func test_no_sfx_when_audio_is_null() -> void:
health.audio = null # also valid — null is handled gracefully
health.take_damage(10)
pass # should not crash
func test_died_signal_emitted_at_zero_health() -> void:
watch_signals(health)
health.take_damage(100)
assert_signal_emitted(health, "died")C# (using GdUnit4)
The GdUnit4 plugin supports C# since v4.4 (the plugin's version, not Godot's). Pin gdUnit4.api 4.3.x on Godot 4.3; 5.x needs Godot 4.4+, and these suites create nodes, so on 5.x mark them [RequireGodotRuntime]. Note: GdUnit4 signal assertions use AssertSignal rather than GUT's watch_signals / assert_signal_emitted. If a node emits a Godot signal from a C# async Task method, GDScript callers cannot await that task directly — emit a Godot signal at completion and await the signal instead.
using GdUnit4;
using static GdUnit4.Assertions;
// StubAudio.cs — a lightweight stand-in for the AudioManager autoload.
// It must be an AudioService to fit the typed Audio property, so PlaySfx is virtual there.
public partial class StubAudio : AudioService
{
public string LastSfx { get; private set; } = "";
public int PlayCount { get; private set; } = 0;
public override void _Ready() { } // skip loading the real sfx library
public override void PlaySfx(string key)
{
LastSfx = key;
PlayCount++;
}
}using System.Threading.Tasks;
using GdUnit4;
using static GdUnit4.Assertions;
[TestSuite]
public partial class HealthComponentTest
{
private HealthComponent _health = null!;
private StubAudio _audioStub = null!;
[BeforeTest]
public void Setup()
{
_audioStub = new StubAudio();
_health = new HealthComponent
{
Audio = _audioStub, // inject the stub — no real AudioManager needed
MaxHealth = 100
};
}
[TestCase]
public void TakeDamage_PlaysHurtSfx()
{
_health.TakeDamage(10);
AssertThat(_audioStub.LastSfx).IsEqual("hurt");
AssertThat(_audioStub.PlayCount).IsEqual(1);
}
[TestCase]
public void TakeDamage_WhenAudioIsNull_DoesNotCrash()
{
_health.Audio = null; // also valid — null is handled gracefully
_health.TakeDamage(10);
// should not throw
}
[TestCase]
public async Task TakeDamage_AtZeroHealth_EmitsDiedSignal()
{
AssertSignal(_health).StartMonitoring();
_health.TakeDamage(100);
await AssertSignal(_health).IsEmitted(HealthComponent.SignalName.Died).WithTimeout(100);
}
}