jame581 / godot-testing

Name: jame581/godot-testing
Author: jame581

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

Version

SKILL.md

9.3 KB

Godot Testing

This skill covers test-driven development (TDD) for Godot 4.3+ projects using GUT (Godot Unit Testing) and gdUnit4. It includes framework selection, full RED-GREEN-REFACTOR examples, test structure, running tests in CI, and common testing patterns.

Related skills: godot-code-review for review checklists, dependency-injection for test-friendly architecture, export-pipeline for CI/CD test automation.

Framework Selection

Feature	GUT	gdUnit4
Language	GDScript-first, limited C#	GDScript + C# (first-class)
Install	AssetLib or git submodule	AssetLib or git submodule
Editor integration	Built-in GUT panel	Built-in inspector + panel
Mocking	`double()` / `stub()` API	`mock()` / `spy()` API
Scene testing	`add_child_autofree()`	`auto_free()` + scene runner
CI support	`gut_cmdln.gd` CLI script	`gdunit4_runner` CLI script
C# support	Minimal (GDScript wrappers only)	Native C# assertions + lifecycle
Maturity	Established (Godot 3 + 4)	Godot 4 focused, actively updated
Best for	Pure GDScript projects	Mixed GDScript/C# or C#-only

Rule of thumb: Use GUT for GDScript-only projects. Use gdUnit4 for C# projects or when you need first-class C# support and scene runner utilities.

TDD Workflow: RED-GREEN-REFACTOR

The standard Test-Driven Development cycle: write a failing test (RED), write minimal code to pass (GREEN), then refactor without breaking the test. Each step has its own discipline — don't skip RED (you'll write tests that pass trivially), and don't skip REFACTOR (technical debt compounds).

See [references/tdd-workflow.md](references/tdd-workflow.md) for a worked GDScript + C# example walking through all three steps on a HealthComponent.

Test Directory Structure

res://
├── src/
│   └── components/
│       ├── health_component.gd
│       └── HealthComponent.cs
└── tests/
    ├── unit/
    │   ├── test_health_component.gd      # GUT: test_ prefix required
    │   └── HealthComponentTest.cs        # gdUnit4 C#: [TestSuite] attribute
    ├── integration/
    │   ├── test_player_scene.gd
    │   └── PlayerSceneTest.cs
    └── gut_config.json                   # GUT configuration (optional)

Naming conventions

Framework	GDScript file	C# file	Test method prefix/attribute
GUT	`test_*.gd`	N/A	`func test_*()`
gdUnit4	`test_*.gd`	`*Test.cs`	`func test_*()` / `[TestCase]`

Running Tests

Both frameworks ship a CLI runner. GUT: addons/gut/gut_cmdln.gd invoked via godot --headless --path . -s addons/gut/gut_cmdln.gd. gdUnit4: --add-gdunit-test-runner argument, or via the editor "GdUnit Tests" dock. CI: tag-triggered or PR-triggered GitHub Action that installs Godot, runs the suite, exits non-zero on failure.

See [references/running-tests.md](references/running-tests.md) for full GUT and gdUnit4 CLI invocations + a copy-pasteable GitHub Actions workflow.

Testing Patterns

Four common patterns: scenes with nodes (instantiate via add_child in before_each, free in after_each), signal testing (assert that emitting works and connect-then-emit fires), mocking/doubling (gdUnit4 Mock<T> or hand-rolled fakes via @export injection), async (await yields, signals, frames in tests).

See [references/testing-patterns.md](references/testing-patterns.md) for full code on each pattern (GDScript + C# where applicable).

Common Assertions

GUT assertions

Assertion	Description
`assert_eq(actual, expected)`	Equality
`assert_ne(actual, expected)`	Not equal
`assert_true(value)`	Is truthy
`assert_false(value)`	Is falsy
`assert_null(value)`	Is null
`assert_not_null(value)`	Is not null
`assert_gt(actual, expected)`	Greater than
`assert_lt(actual, expected)`	Less than
`assert_gte(actual, expected)`	Greater than or equal
`assert_lte(actual, expected)`	Less than or equal
`assert_has(collection, item)`	Collection contains item
`assert_does_not_have(collection, item)`	Collection does not contain item
`assert_string_contains(str, sub)`	String contains substring
`assert_almost_eq(actual, expected, margin)`	Float equality within margin
`assert_signal_emitted(obj, signal_name)`	Signal was emitted
`assert_signal_not_emitted(obj, signal_name)`	Signal was not emitted

gdUnit4 assertions (GDScript + C#)

GDScript	C#	Description
`assert_that(val).is_equal(exp)`	`AssertThat(val).IsEqual(exp)`	Equality
`assert_that(val).is_not_equal(exp)`	`AssertThat(val).IsNotEqual(exp)`	Not equal
`assert_that(val).is_true()`	`AssertThat(val).IsTrue()`	Is true
`assert_that(val).is_false()`	`AssertThat(val).IsFalse()`	Is false
`assert_that(val).is_null()`	`AssertThat(val).IsNull()`	Is null
`assert_that(val).is_not_null()`	`AssertThat(val).IsNotNull()`	Is not null
`assert_that(val).is_greater(exp)`	`AssertThat(val).IsGreater(exp)`	Greater than
`assert_that(val).is_less(exp)`	`AssertThat(val).IsLess(exp)`	Less than
`assert_that(val).is_between(min, max)`	`AssertThat(val).IsBetween(min, max)`	In range (inclusive)
`assert_that(arr).contains([a, b])`	`AssertThat(arr).Contains(a, b)`	Array contains elements
`assert_that(str).contains("sub")`	`AssertThat(str).Contains("sub")`	String contains substring
`assert_that(val).is_approximately(exp, margin)`	`AssertThat(val).IsApproximately(exp, margin)`	Float within margin
`assert_signal(mon).is_emitted("name")`	`AssertSignal(mon).IsEmitted("name")`	Signal emitted

What NOT to Test

Avoid testing things that add noise without catching real bugs:

Godot engine internals — do not assert that Node.add_child() works or that @export variables show up in the editor
Private implementation details — test behavior through the public API; if a refactor breaks a test that covers only private state, the test is wrong
Visual/rendering output — pixel-level rendering results are brittle; test the data driving the visuals instead
Timing-sensitive floats without margins — use assert_almost_eq / IsApproximately for physics values
One-liners that wrap a built-in — a property getter that just returns a field needs no test
Every possible invalid input — test the documented contract, not every imaginable misuse

Checklist

[ ] Each test file matches the naming convention for the chosen framework (test_*.gd / *Test.cs)
[ ] Tests extend the correct base class (GutTest / GdUnit4.GdUnitTestSuite)
[ ] Nodes added to the scene tree use add_child_autofree or auto_free — never manual queue_free()
[ ] Signals are watched before the action that triggers them
[ ] Mocks/doubles are used for external dependencies, not for the unit under test
[ ] Each test covers exactly one behavior (one logical assertion per test)
[ ] CI workflow runs tests headlessly on every push and PR
[ ] Flaky async tests use explicit timeouts, not arbitrary sleep durations
[ ] Tests pass before merging (RED is only acceptable while actively implementing)