Installation

1. Install the CLI

Via Cargo:

cargo install gdtest

Requires Rust 1.96 or later.

Or download a binary from the GitHub releases page:

Put the gdtest binary on your PATH.

If you do not want to put it on PATH, the Godot editor plugin can still use GDTEST_BIN=/path/to/gdtest.

2. Set the Godot executable (if needed)

gdtest first tries explicit configuration. If nothing is set, it falls back to best-effort auto-discovery across common command names and common install locations.

1. --godot-exe CLI flag
2. GODOT_EXE environment variable
3. GODOT_EXE in a .env file at your project root
4. godot_exe key in gdtest.toml

If your binary is named differently (e.g. godot4) or is not on PATH, set it in any of the above locations:

# gdtest.toml
godot_exe = "godot4"

# .env (auto-loaded by gdtest from the project root)
GODOT_EXE=/Applications/Godot.app/Contents/MacOS/Godot

3. Initialize the project

Run this from your Godot project root:

gdtest init

This installs addons/gdtest/ into the project:

your-project/
`-- addons/
    `-- gdtest/
        |-- gdtest_worker.gd
        |-- gdt.gd
        `-- gd_test.gd

The runtime addon is also included in each release archive.

4. Editor integrations

Godot editor plugin:

1. gdtest init installs it by default.
2. Enable gdtest Editor in Project -> Project Settings -> Plugins.
3. The panel resolves the gdtest binary in this order:
   • GDTEST_BIN
   • .gdsuite/tools/gdtest/bin/gdtest (gdtest.exe on Windows), where gdsuite installs gdtest, so a gdsuite-managed project needs no extra setup
   • nearby project-local binaries
   • gdtest on PATH

If you only want the runtime harness:

gdtest init --no-editor

VS Code and Zed: the extensions are not published to a marketplace yet, so build them from a clone of the repository with just:

just package-vscode     # writes vscode-gdtest/vscode-gdtest-<version>.vsix
code --install-extension vscode-gdtest/vscode-gdtest-*.vsix

Optional VS Code settings:

{
  "gdtest.executablePath": "gdtest",
  "gdtest.testDirectory": "test/"
}

rustup target add wasm32-wasip1
just package-zed        # writes zed-gdtest/extension.wasm

Then in Zed, run zed: install dev extension and pick the zed-gdtest/ folder.

Compatibility

The addon and CLI are versioned together and released in the same archive. The addon's major and minor version must match the CLI's: if they don't, gdtest stops with an error telling you to update addons/gdtest/ (gdtest init --force does it).

You can always check which harness version is installed by looking for HARNESS_VERSION at the top of addons/gdtest/gdtest_worker.gd.

Verify

gdtest --version
gdtest test/

Next: Quickstart