GUT (Godot Unit Test)

GUT (Godot Unit Test) is a unit testing framework designed specifically for the Godot Engine. It allows developers to write tests for their GDScript code using GDScript itself.

Version Compatibility:

• GUT 9.x: Designed for Godot 4.x.
• GUT 7.x: Designed for Godot 3.x.

GUT provides several advanced testing capabilities:

• Asserts and Utility Methods: A wide range of methods to simplify test assertions.
• Inner Test Classes: Support for nesting test classes to improve context and maintainability.
• Doubles: Supports Full Doubles, Partial Doubles, Stubbing, and Spies.
• Parameterized Tests: Ability to run the same test with different sets of data.
• CLI: A Command Line Interface for running tests outside the editor.
• JUnit XML Export: Export test results in the standard JUnit XML format for CI/CD integration.

GUT uses a toolkit to generate RST files from code comments via XML. This process requires zsh, python3, and Docker.

Prerequisites:

1. The project must have been opened in the Godot editor or you must have run godot --import to ensure XML files can be generated.
2. The Docker image must be built (see Local Documentation Generation).
3. The environment variable GODOT must be set to the path of your Godot executable.

Execution: Run the following from the root of the project:

zsh documentation/generate_rst.sh

Outputs:

• XML: documentation/class_ref_xml
• RST: documentation/docs/class_ref
• HTML: documentation/docs/_build/html/class_ref

GUT versions are strictly tied to Godot versions. Ensure you download the version compatible with your current Godot engine to avoid compatibility issues:

• GUT 9: Requires Godot 4.
• GUT 7: Requires Godot 3.4.

If GUT does not appear in the Godot Asset Library, it is likely because your current Godot version is incompatible with the version of GUT available.

GUT supports pre-run and post-run hooks to perform initialization or verify test results. To create a hook, you must create a script that inherits from GutHookScript and implements the run() method.

Important: Do not use _init() for logic requiring the GUT instance, as the gut property is assigned after initialization. Use the run() method instead.

GUT supports external test execution:

• Command Line: Use the GUT CLI (refer to the [Command Line] documentation for specific flags).
• VSCode: Use the gut-extension to run tests directly from your editor.

To preview the documentation locally, use Docker Compose from the documentation directory.

1. Build the image (only required once):

   docker-compose -f docker/compose.yml build

2. Generate and run the documentation server:

   docker-compose -f docker/compose.yml up

3. View the output: Open documentation/docs/_build/html/index.html in your browser.

# From the documentation directory
docker-compose -f docker/compose.yml build
docker-compose -f docker/compose.yml up

When stubbing doubled scenes, use the path to the scene, not the path to the scene's script. If you stub the script instead of the scene, the instance created from double(scene) will not use the stubbed values.

Requirement: For a scene to be doubled, its script must be instantiable with new() using zero parameters.

var DoubleThisScene = load('res://double_this_scene.tscn')

func test_illustrate_stubbing_scenes():
  var doubled_scene = double(DoubleThisScene).instantiate()
  stub(doubled_scene, 'return_hello').to_return('world')

  assert_eq(doubled_scene.return_hello(), 'world')

GUT does not have native global function hooks. To perform logic across every GutTest instance (e.g., global setup/teardown), you must connect to the signals available on the gut instance within a GutHookScript using a Pre-Run Hook.

By connecting custom functions to these signals during the run() method of your GutHookScript, you can define global behavior once instead of repeating it in every test class.

extends GutHookScript

func run():
    gut.start_test.connect(_on_test_started)

func _on_test_started(test_name):
    # setup logic run before every test in every test script goes here