gdUnit4 testing framework integration for Godot

version
2.3.3
GitHub stars
14

Install

/plugin install gdunit4-toolkit@claude-godot-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add minami110/claude-godot-tools.

Contents

Discovered from source

Skills 2

GDScript Test

Run GDUnit4 tests using the gdunit4-test-runner binary.

CRITICAL: Read-Only Operation

  • This is a read-only operation.
  • Run the binary and report results. DO NOT edit files or attempt to fix failing tests.
  • If tests fail, report file path, line number, assertion details — then STOP.
  • NEVER use addons/gdUnit4/runtest.sh or direct godot commands.

When to Use

  • After implementing new features
  • After modifying GDScript files
  • When you need to verify test coverage
  • When running CI/CD validation locally

Setup

The binary is installed automatically on first use (via a skill hook). To install manually:

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/scripts/install.sh

Test Execution

Run tests using the binary directly.

Run All Tests

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner

Scans entire project for tests.

Run Specific Test File

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner tests/test_foo.gd

Run Multiple Tests

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner tests/test_foo.gd tests/test_bar.gd

Run Tests in Directory

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner tests/application/

Verbose Mode

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner --verbose

Shows all Godot logs (useful for debugging test issues).

Custom Godot Path

${CLAUDE_PLUGIN_ROOT}/skills/gdunit4-test-runner/bin/gdunit4-test-runner --godot-path /path/to/godot

Understanding Results

The binary outputs test results in JSON format for easy parsing.

Success

{
  "summary": {
    "total": 186,
    "passed": 186,
    "failed": 0,
    "crashed": false,
    "status": "passed"
  },
  "failures": []
}

Failure

{
  "summary": {
    "total": 10,
    "passed": 8,
    "failed": 2,
    "crashed": false,
    "status": "failed"
  },
  "failures": [
    {
      "class": "TestClassName",
      "method": "test_method_name",
      "file": "res://tests/test_file.gd",
      "line": 42,
      "expected": "expected_value",
      "actual": "actual_value",
      "message": "FAILED: res://tests/test_file.gd:42"
    }
  ]
}

Crash

{
  "summary": {
    "total": 5,
    "passed": 3,
    "failed": 0,
    "crashed": true,
    "status": "crashed"
  },
  "crash_details": {
    "crash_info": "...",
    "script_errors": "..."
  },
  "failures": []
}

crashed means Godot crashed (handle_crash:) or no test report was produced (e.g. a test script failed to compile). Only tests completed before the crash are reported.

Script Errors

SCRIPT ERROR: lines alone do NOT mark a run as crashed. When a complete report exists, they appear in crash_details.script_errors as diagnostics while status stays passed or failed. Mention them in the report if present.

Exit Codes

  • 0: All tests passed
  • 1: Some tests failed
  • 2: Crash or error (e.g., Godot crashed, report file not found)

Notes

  • Binary automatically changes to project root before running tests
  • Test reports are saved in reports/ directory
  • Uses gdUnit4 framework (configured in project.godot)
  • Compatible with CI/CD environments
  • Binary handles Godot existence check and error handling internally

gdUnit4 Test Writer

Write gdUnit4 test code for GDScript files with proper assertions and test structure.

Workflow

  1. Analyze target file - Read the GDScript file to understand what needs testing
  2. Check gdUnit4 docs - Use Context7 (/websites/godot-gdunit-labs_github_io_gdunit4) if needed
  3. Select assertions - Use type-specific assertions (see [references/assertions.md])
  4. Create test file - Place in res://tests/ directory with test_*.gd naming (e.g., test_player.gd)

Quick Reference

Test File Template

extends GdUnitTestSuite

func test_example() -> void:
    assert_int(1).is_equal(1)

Common Assertions

  • int: assert_int(value).is_equal(10)
  • float: assert_float(value).is_equal_approx(3.14, 0.01)
  • String: assert_str(text).contains("hello")
  • Array: assert_array(items).has_size(5)
  • Object: assert_object(node).is_not_null()
  • Signal: await assert_signal(emitter).is_emitted(emitter.my_signal) (Signal reference preferred; string name also accepted)

Memory Management

func test_with_node() -> void:
    var node: Node = auto_free(Node.new())  # Auto-freed after test
    assert_object(node).is_not_null()

Version Compatibility

gdUnit4Godot
v6.x4.5+
v5.x4.3 – 4.4.1
v4.4.0+4.2+

These references target gdUnit4 v6. Pre-v6 array-style arguments (e.g. contains([1, 2]), is_emitted("sig", [args])) are still accepted for backward compatibility, but prefer the v6 variadic style shown here.

References

Context7 Library ID

For detailed gdUnit4 documentation:

  • Library ID: /websites/godot-gdunit-labs_github_io_gdunit4

Sponsors

Details

Marketplace
minami110/claude-godot-tools
Source
gdunit4-toolkit
Category
Development
License
MIT

More from minami110/claude-godot-tools

All 4