Writing Tests

Introduction

This guide provides instructions on how to write tests using the GUT (Godot Unit Testing) library for Tribe of the Accord. Tests are crucial for ensuring that the game's functionality works as expected and remains stable throughout development. Especially when it becomes a commercially maintained project and capturing regressions is done before an official release.

Library used - https://github.com/bitwes/Gut (Version 7+) Version 9 is for Godot 4+
Documentation - https://gut.readthedocs.io/en/godot_3x

Test File Structure

To maintain consistency and ensure every source file is tested, our project should have a test file for each source file. Test files are named similarly to their corresponding source files but with a .test.gd extension.

Source file: src/Player.gd
Test file: src/Player.test.gd

Test files in our project are created based on the type of asset you are testing: Scripts or Scenes. Here's how you should structure your test files for each type:

Manual Approach

Create a new test file for your source file. E.g. src/Player.test.gd.
Copy the snippet below (Script or Scene templates below).
Replace _FullID.gd to the full path e.g. src/Player.gd
Replace _ID.gd to the full path e.g. Player.gd

For a Script/Reference/Resource file

extends "res://addons/gut/test.gd"

var _Script = load("res://_FullID.gd")
var obj

func before_each():
    obj = _Script.new()

func after_each():
    obj.free()
    obj = null

func after_all() -> void:
    _Script = null

func test_main():
    pending('Need to write test for "_ID"')

For a Scene file

extends "res://addons/gut/test.gd"

const SCENE_PATH = "res://_FullID.tscn"
var scene
var obj = null
var expected_methods = ["_ready"]

func before_each():
    scene = load(SCENE_PATH).instance()
    add_child(scene)

func after_each():
    remove_child(scene)
    scene.free()

func test_main():
    pending('Need to write a test for "_ID"')

We default to a pending function, in the test run it will simply skip the test until you are ready to write some tests.

Generating Test Files

Use the following bash scripts to automatically generate test files for missing tests using Bash scripts found in tools/bin:

For Scene files:

sh tools/bin/create-scene-test-files.sh

For Script and Resource files:

sh tools/bin/create-script-test-files.sh

The downside to this is it will create all test files that are missing in the entire project, but its fine as they are all set as pending tests so it won't impact you unless you add tests to a specific file and they fail.

Writing Your Tests

When you test file has been either manually created or you used the script to generate it for you (which is a lot easier), you are ready to write some tests.

Use assertions to validate the behavior of the object or scene under test. For example:

func test_player_movement():
    obj.move(10, 0)  # Assuming `move` is a method in the Player script
    assert_eq(obj.position.x, 10, "Player should move 10 units along the x-axis")

For some examples of what sort of tests to write, visit this page.

Tribe of the Accord - Documentation