
gdunit4-toolkit
gdUnit4 testing framework integration for Godot
- version
- 2.3.3
- GitHub stars
- 14
Install
/plugin install gdunit4-toolkit@claude-godot-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add minami110/claude-godot-tools.
Contents
Discovered from sourceSkills 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.shor directgodotcommands.
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
- Analyze target file - Read the GDScript file to understand what needs testing
- Check gdUnit4 docs - Use Context7 (
/websites/godot-gdunit-labs_github_io_gdunit4) if needed - Select assertions - Use type-specific assertions (see [references/assertions.md])
- Create test file - Place in
res://tests/directory withtest_*.gdnaming (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
| gdUnit4 | Godot |
|---|---|
| v6.x | 4.5+ |
| v5.x | 4.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
- references/assertions.md - Complete assertion reference
- references/test-structure.md - Test lifecycle and structure
- references/signals.md - Signal testing guide
- references/scene-runner.md - Scene runner for integration tests
- references/parameterized-tests.md - Parameterized tests and fuzzing
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