Index of every page on this site: llms.txt
All skills
jame581 avatar

/godot-testing

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

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

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/godot-testing

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈31 tokens for metadata: the name and description. ≈2.4k when used: this file. ≈8.6k more on demand in 5 files.

Description uses 1.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈122 characters, or 1.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 runtest.sh / GdUnitCmdTool.gd
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://
├── .gutconfig.json                       # GUT default config file (optional)
├── src/
│   └── components/
│       ├── health_component.gd
│       └── HealthComponent.cs
└── tests/
    ├── unit/
    │   ├── test_health_component.gd      # GUT: test_ prefix (default -gprefix)
    │   └── HealthComponentTest.cs        # gdUnit4 C#: [TestSuite] attribute
    └── integration/
        ├── test_player_scene.gd
        └── PlayerSceneTest.cs

Naming conventions

Framework GDScript file C# file Test method prefix/attribute
GUT test_*.gd N/A func test_*()
gdUnit4 any name (*_test.gd when generated) *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 -gexit (without -gexit the run never quits). gdUnit4: addons/gdUnit4/runtest.sh -a res://tests (wraps bin/GdUnitCmdTool.gd; under --headless it also needs --ignoreHeadlessMode), or the editor's GdUnit 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() in GDScript; in C#, 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
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_equal_approx(exp, margin) AssertThat(val).IsEqualApprox(exp, margin) Float within margin
await assert_signal(mon).is_emitted("name") await AssertSignal(node).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 / IsEqualApprox 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 (GUT test_*.gd; gdUnit4 *_test.gd / *Test.cs)
  • Tests extend the correct base class (GutTest / GdUnitTestSuite); C# gdUnit4 suites are plain [TestSuite] classes
  • C#: gdUnit4.api pinned to 4.3.x on Godot 4.3; on 5.x (Godot 4.4+), suites that touch nodes or scenes carry [RequireGodotRuntime]
  • 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)

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning8d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    This skill provides comprehensive instructions and code examples for implementing test-driven development in Godot projects using GUT and gdUnit4 frameworks. It includes legitimate commands for installing official tools and running tests locally and in CI environments.

  • Socket8d

    No alerts

  • Snyk8d

    Risk: MEDIUM · 1 issue

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last month

README badge

README badge for jame581/godotprompter/godot-testing