Skip to content
Grid Building Docs

GdUnit Testing

This guide explains how to run the plugin test suite using the GdUnit4 GUI test runner. It follows the official GdUnit4 “first steps” and “getting started” guidance and documents the tested versions.

Grid Building 5.0.0 includes extensive automated testing:

  • 1540 tests passing at 100% (1410 plugin tests + 130 demo/misc tests)
  • Comprehensive coverage of collision calculations, validation rules, and dependency injection
  • Complete system validation across all core systems and components

Versions

  • gdUnit: 6.0.0 (for Godot 4.5)
  • Godot: 4.5 (stable) - test environment
  • Grid Building plugin: 5.0.0 (supports Godot 4.4.0, 4.4.1, 4.5 stable)

Overview

  • Use the Godot editor and the GdUnit4 GUI test interface to run tests.
  • The test-suite lives in a separate repository: https://github.com/ChrisTutorials/grid_building_test
  • When running tests against a released plugin, download the matching release from the grid_building_test repository releases and run the tests against the plugin version you have installed.

GdUnit Testing

Section titled “GdUnit Testing”

This guide helps contributors run the Grid Building test-suite (using gdUnit4) against the demo or the plugin source.

Supported versions

Section titled “Supported versions”
  • gdUnit: 6.0.0 (for Godot 4.5)
  • Godot: 4.5 (stable) - test environment
  • Grid Building plugin: 5.0.0 (supports Godot 4.4.0, 4.4.1, 4.5 stable)

Quick overview

Section titled “Quick overview”
  • The demo project intentionally omits author-specific shell helpers. Use the Godot editor + gdUnit4 GUI for the most reliable experience.
  • The test-suite is maintained in a separate repository: https://github.com/ChrisTutorials/grid_building_test
  • To test a released plugin version, download the matching test-suite release (same tag) and run tests against the plugin you have installed.

Quick start (GUI — recommended)

Section titled “Quick start (GUI — recommended)”
  1. Download or clone the test-suite (instructions below).
  2. Open the demo project (or your plugin project) in Godot 4.4.0, 4.4.1, or 4.5 (stable).
  3. Install and enable the gdUnit4 editor plugin (6.0.0 for Godot 4.5).
  4. Add the test-suite folder to the gdUnit4 test runner dock and run tests.

Download / prepare the test-suite

Section titled “Download / prepare the test-suite”

You can either download a release archive or clone the test-suite repository and check out the matching tag.

Example (clone & checkout):

Terminal window
git clone https://github.com/ChrisTutorials/grid_building_test.git
cd grid_building_test
git checkout tags/v5.0.0

Place the grid_building_test folder next to your demo project (or inside a workspace) so that resolving res:// paths is straightforward. A common layout is:

  • demo-project/
  • grid_building_test/

If you prefer to extract a downloaded release archive, put the extracted folder in a similar relative location.

Install gdUnit4 (editor plugin)

Section titled “Install gdUnit4 (editor plugin)”

Follow the official installation docs for gdUnit4.

Quick steps:

  1. Open Godot Editor 4.4.0, 4.4.1, or 4.5 (stable).
  2. Open your demo/project workspace.
  3. Install gdUnit4 as an Editor Plugin and enable it via Editor → Manage Plugins.

Official docs: https://mikeschulze.github.io/gdUnit4/first_steps/getting-started/

Running tests with the GUI (step-by-step)

Section titled “Running tests with the GUI (step-by-step)”
  1. With your project open in Godot, enable gdUnit4 from Editor → Manage Plugins.
  2. Open the gdUnit4 dock/panel in the editor (it may appear as a tab or docked panel).
  3. In the dock, use the folder selector to add the test-suite folder. Example relative path: res://../grid_building_test/test/ (adjust according to where you placed the tests).
  4. Select a test folder or a single test file and click the run button. Use the UI options to run all tests or rerun failures.
  5. Inspect results and stack traces in the dock. Click test rows to open failing scenes or lines in the editor.

Command-line / CI (optional)

Section titled “Command-line / CI (optional)”

If you need headless or CI runs, consult the gdUnit4 documentation for recommended approaches and example commands. You will typically run Godot in a headless mode and point it to the test runner configuration.

Notes:

Common troubleshooting

Section titled “Common troubleshooting”

  • Tests can’t find res:// resources

    • Ensure the demo project and the test-suite are in the same Godot project/workspace so res:// references resolve correctly.

  • Version mismatch or plugin not loaded

    • Verify you are using the gdUnit4 release compatible with your Godot version (6.0.0 for Godot 4.5) and that the plugin version matches the tests (e.g., plugin v5.0.0 with grid_building_test v5.0.0).

  • Flaky tests or engine differences

    • Run the failing test in isolation in the editor to inspect scene state and full traces.

FAQ

Section titled “FAQ”

Q: Where is the test-suite repository? A: https://github.com/ChrisTutorials/grid_building_test

Q: Can I run tests without the editor? A: Yes — gdUnit4 supports headless/CI runs. See the gdUnit4 docs for examples and recommended configuration.

Further reading

Section titled “Further reading”