godot-testing

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)