GdUnit4 Documentation

GdUnit4 provides several advanced testing techniques to help write comprehensive and effective tests for Godot games. These techniques allow you to move beyond basic assertions into complex scenarios like signal monitoring, automated fuzzing, and dependency isolation.

Prerequisites

• A basic understanding of the Godot engine and GDScript.
• GdUnit4 must be installed and configured in your Godot project.

GdUnit4 provides several integrated features for the Godot editor:

• GDScript and C# Support: Write and execute tests in both languages.
• Embedded Test Inspector: Navigate test suites directly within the Godot editor.
• Test Discovery: Automatically finds tests at runtime and populates the inspector.
• Convenient Interface: Run test suites via context menus in the FileSystem panel, ScriptEditor, or GdUnit Inspector.
• Automated Test Generation: Right-click any function in the ScriptEditor and select "Create TestCase" to generate a test automatically.

For C# users, GdUnit4 provides specialized support through GdUnit4Net:

• C# API: Full support for writing tests in C#.
• VSTest Integration: Run and debug tests in Visual Studio, Visual Studio Code, or JetBrains Rider using the gdunit4.test.adapter.

The GdUnit Test Inspector is the central interface for running tests and reviewing results within Godot. It consists of four main areas:

1. Button Bar: Controls for triggering test runs (Runtime, Debug, or Overall).
2. Status Bar: Provides real-time execution progress, elapsed time, and counts for errors, failures, flaky tests, skipped tests, and orphan nodes.
3. Test Run Overview Tree: A real-time hierarchical or flat list of all executed tests showing their status and execution time.
4. Failure Report: Detailed breakdown of assertion mismatches (expected vs. current) and the full clickable call stack for debugging.

Test Driven Development (TDD) is a methodology where tests are written before the actual implementation code. Using GdUnit4 for TDD follows a specific cycle:

1. Write a failing test: Define the expected behavior of a component using GdUnit4 test suites.
2. Write minimum code: Implement only the amount of code necessary to make the test pass.
3. Refactor: Improve the code design while ensuring the tests continue to pass.

By using GdUnit4 to drive development, you ensure that your Godot code meets requirements and remains reliable through automated verification.

The Scene Runner is a tool for integration testing by simulating interactions on a scene, such as keyboard/mouse input and scene processing over a specific number of frames.

Key constraints:

• Managed by the GdUnit API and automatically freed after use.
• One Scene Runner can only manage one scene. To test multiple scenes, create a separate runner for each.

Initialization:

• In GDScript: Use scene_runner("<scene_path>").
• In C#: Use ISceneRunner.Load("<scene_path>").

# GDScript
var runner := scene_runner("res://my_scene.tscn")

// C#
ISceneRunner runner = ISceneRunner.Load("res://my_scene.tscn");

Integration testing in GdUnit4 focuses on verifying the interaction between multiple components, modules, or scenes within your game, rather than testing individual components in isolation (unit testing). It is used to identify issues such as:

• Interaction Bugs: Conflicts between different input actions (e.g., keyboard vs. mouse).
• Scene Transitions: Ensuring smooth transitions between different scenes or UI states.
• Gameplay Logic: Verifying mechanics when multiple elements interact (e.g., player actions vs. enemy behavior).

By using integration tests, you can achieve early bug detection and improved stability when updating individual parts of your game.

Unit testing is the practice of testing individual components or 'units' of your code in isolation to ensure they work as expected. In the context of Godot development with GdUnit4, a unit typically refers to a single function, method, or class.

Key Characteristics:

• Isolation: Tests target specific code independently of the rest of the system, making it easier to pinpoint the source of an issue.
• Automation: Tests can be run frequently and consistently to catch regressions.
• Speed: Tests are small and focused on a single piece of functionality (e.g., movement logic or score calculation), allowing for rapid execution.

A TestSuite is a collection of tests aligned to a specific class or module. It is used to manage test data and environment consistency by providing hooks for setup and teardown.

Key capabilities include:

• Grouping: Organizing multiple test cases related to a single unit of code.
• Lifecycle Management: Defining pre-initialized test data and cleanup routines.
• Granular Hooks: Executing logic at different levels of the test lifecycle (before/after each test case, and before/after the entire suite).

A Spy is used to verify behavior during a test by tracking all function calls and their parameters on an instance.

Unlike a Mock, which replaces the implementation, a Spy calls the real implementation. It behaves exactly like the normal instance while recording its interactions for later verification.

Note: This implementation is only available for GDScript. For C#, use existing frameworks like Moq.

GdUnit distinguishes between parameter equality (value comparison) and reference equality (instance comparison).

• Parameter Equality: Two different instances are considered equal if they are of the same type and have the same parameter values. Use is_equal and is_not_equal via assert_object.
• Reference Equality: Checks if two variables point to the exact same memory instance. Use is_same and is_not_same via assert_object, or specialized functions like contains_same or not_contains_same for collections.

# Parameter equality (different instances, same values)
assert_object(obj1).is_equal(obj2)

# Reference equality (same instance)
assert_object(obj1).is_same(obj2)