Loading...
Loading...
Testing Godot 4 GDScript projects - a zero-dependency headless check scene, gdUnit4 and GUT suites, scene-runner tests, signal assertions, and CI commands. Use when adding tests to a Godot project, setting up CI, or proving a change did not break the game.
npx skill4agent add affaan-m/ecc godot-testing| Layer | What it checks | Needs a window? | Speed |
|---|---|---|---|
| 1. Logic tests | Pure rules in | No | Milliseconds |
| 2. Scene tests | A scene loads, nodes wire up, signals fire, a few frames run | No (usually) | Seconds |
| 3. Playtest | Feel, balance, fun | Yes, human | Minutes |
godot-patterns# tests/verify_logic.gd, attached to the root Node of tests/verify_logic.tscn
extends Node
## A tiny headless test runner. Run it with:
## godot --headless --path . res://tests/verify_logic.tscn
var _passed: int = 0
var _failed: int = 0
func _ready() -> void:
# Each _test_* function is one group of related checks.
_test_inventory_clamps_to_stack()
_test_health_never_negative()
print("%d passed, %d failed" % [_passed, _failed])
# A non-zero exit code is what tells CI the run failed.
get_tree().quit(1 if _failed > 0 else 0)
## Records one assertion and prints a line only when it fails.
func _check(condition: bool, message: String) -> void:
if condition:
_passed += 1
else:
_failed += 1
push_error("FAIL: " + message) # push_error also shows in the debugger
func _test_inventory_clamps_to_stack() -> void:
var inv := Inventory.new()
var added: int = inv.add(&"wood", 150)
_check(added == Inventory.MAX_STACK, "add() clamps to MAX_STACK")
_check(inv.add(&"wood", 1) == 0, "a full stack accepts nothing more")
func _test_health_never_negative() -> void:
var health := Health.new() # a Node, so we free it ourselves at the end
health.damage(health.maximum + 50)
_check(health.current == 0, "health floors at zero")
health.free()godot -s script.gd--scriptaddons/gdUnit4# tests/test_inventory.gd
extends GdUnitTestSuite
## gdUnit4 finds methods whose names start with test_.
func test_add_clamps_to_stack() -> void:
var inv := Inventory.new()
var added: int = inv.add(&"wood", 150)
# Fluent assertion: assert_int(actual).is_equal(expected)
assert_int(added).is_equal(Inventory.MAX_STACK)
func test_add_emits_signal() -> void:
var inv := Inventory.new()
# monitor_signals lets us ask later whether a signal fired.
var monitor := monitor_signals(inv)
inv.add(&"wood", 5)
await assert_signal(inv).is_emitted("item_added", &"wood", 5)before()after()before_test()after_test()auto_free(...)add_child(auto_free(node))func test_player_moves_right() -> void:
# scene_runner loads the scene and lets us drive it like a player would.
var runner := scene_runner("res://scenes/main.tscn")
runner.simulate_action_pressed(&"move_right") # uses InputMap action names
await runner.simulate_frames(30) # let 30 frames pass
var player := runner.find_child("Player") as Node2D
assert_object(player).is_not_null()
assert_float(player.position.x).is_greater(0.0)func test_with_mock() -> void:
var mock_node := mock(Node) # a stand-in with the real method names
mock_node.get_name()
verify(mock_node).get_name() # asserts it was called exactly once# Run every suite in tests/. Replace the path with your Godot executable if it is not on PATH.
godot --path . -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests-a <dir or file>-i <suite>-c--ignoreHeadlessModesimulate_*xvfbruntest.sh# test/unit/test_health.gd
extends GutTest # GUT discovers methods starting with test_
func test_health_floors_at_zero() -> void:
var health := autofree(Health.new()) # autofree = freed after the test
health.damage(999)
assert_eq(health.current, 0, "health floors at zero")godot --headless --path . -s addons/gut/gut_cmdln.gd -gdir=res://test -gexit-gexitgut_cmdln.gd-gh| You are... | Pick |
|---|---|
| Starting out, small project | A (check scene), then graduate |
| Want scene-runner and mocks, GDScript and C# | B (gdUnit4) |
| Already using GUT | C, and do not mix two frameworks |
# Parse a script and exit: catches syntax errors without running the game.
# Caveat: autoloads are not registered here, so scripts that use an autoload name
# report "Identifier not found" even though the game runs fine. The boot check below
# is the authoritative compile test.
godot --headless --path . --check-only --script res://scripts/player.gd
# Boot the project, load the main scene, and quit after a few frames. Catches load-time errors.
godot --headless --path . --quit-after 5
# Rebuild the import cache (needed on a fresh CI checkout before tests can load assets).
godot --headless --path . --import# .github/workflows/tests.yml (outline only; pin versions you have tested)
steps:
- uses: actions/checkout@v4
- name: Install Godot # use your preferred Godot setup action or a pinned download
run: echo "install a pinned Godot build here"
- name: Import assets
run: godot --headless --path . --import
- name: Run tests
run: godot --headless --path . res://tests/verify_logic.tscn.godot/| Pitfall | Fix |
|---|---|
| Tests pass locally, fail on CI | Missing import step. Run |
| Input simulation does nothing headless | Headless drops input events. Test the logic layer instead, or use a display. |
| Leaked nodes and orphan warnings | |
| Test depends on frame timing | |
| Tests share state through an autoload | Reset the autoload in |
| One giant test | One behavior per test, named for the behavior. |
| Randomness makes tests flaky | Seed a |
godot-patternstdd-workflowtdd-guidegdscript-reviewer