godot-testing
Use when writing tests for Godot projects — TDD workflow with GUT and gdUnit4, covers both GDScript and C#
jame581 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jame581/GodotPrompter --skill godot-testingAbout this skill
name: godot-testing description: Use when writing tests for Godot projects — TDD workflow with GUT and gdUnit4, covers both GDScript and C#
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 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 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 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 | |-----------------------------------
Read the complete source ↗