gut-test-writer

GUT Test Writer

Generate GUT tests. For GdUnit4, see the qa-tester agent — same patterns, different API.

Setup (once per project)

1. Install GUT via Asset Library or git submodule into addons/gut/
2. Enable in Project Settings → Plugins
3. Create test/.gutconfig.json:

{
  "dirs": ["res://test/unit", "res://test/integration"],
  "include_subdirs": true,
  "log_level": 1,
  "should_exit": true,
  "should_exit_on_success": true,
  "junit_xml_file": "res://test/reports/results.xml",
  "junit_xml_timestamp": false
}

1. Add to .gitignore: test/reports/

Directory structure

test/
├── unit/
│   ├── test_health_component.gd
│   ├── test_inventory.gd
│   └── test_state_machine.gd
├── integration/
│   ├── test_player_takes_damage.gd
│   └── test_save_load_roundtrip.gd
├── helpers/
│   ├── test_helpers.gd       # shared fixtures
│   └── mock_player.gd
├── fixtures/
│   └── test_save_data.tres
├── reports/                  # gitignored
└── .gutconfig.json

Filename convention: test_{thing_under_test}.gd. Class: extends GutTest.

Test template

extends GutTest
## Tests for HealthComponent.

const HealthComponent := preload("res://scripts/components/health_component.gd")

var _hp: HealthComponent

func before_each() -> void:
    _hp = HealthComponent.new()
    _hp.max_health = 100
    add_child_autofree(_hp)
    _hp._ready()  # _ready is called when added; explicit here for clarity

func test_starts_at_full_health() -> void:
    assert_eq(_hp.current_health, 100)

func test_take_damage_reduces_health() -> void:
    _hp.take_damage(30)
    assert_eq(_hp.current_health, 70)

func test_take_damage_clamps_at_zero() -> void:
    _hp.take_damage(9999)
    assert_eq(_hp.current_health, 0)

func test_die_signal_emitted_at_zero() -> void:
    watch_signals(_hp)
    _hp.take_damage(100)
    assert_signal_emitted(_hp, "died")

func test_health_changed_payload() -> void:
    watch_signals(_hp)
    _hp.take_damage(25)
    assert_signal_emitted_with_parameters(_hp, "health_changed", [100, 75])

func test_invulnerable_blocks_damage() -> void:
    _hp.invulnerable = true
    _hp.take_damage(50)
    assert_eq(_hp.current_health, 100)

func test_heal_does_not_overshoot_max() -> void:
    _hp.take_damage(20)
    _hp.heal(50)
    assert_eq(_hp.current_health, 100)

func test_revive_after_death() -> void:
    _hp.take_damage(100)
    watch_signals(_hp)
    _hp.revive()
    assert_signal_emitted(_hp, "revived")
    assert_eq(_hp.current_health, 100)