Quickstart

1. Install the CLI

cargo install gdtest

Requires Rust 1.85+. Or download a binary from Installation.

2. Initialize the project

Run this from your Godot project root:

gdtest init

That writes addons/gdtest/ into your project:

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

The addon and the CLI are versioned together. gdtest init installs the bundled runtime that matches your CLI version.

gdtest init also installs the Godot editor plugin by default. Pass --no-editor if you only want the runtime harness.

If you want the editor panel, enable gdtest Editor once in Project -> Project Settings -> Plugins.

3. Configure Godot (if needed)

gdtest first tries --godot-exe, GODOT_EXE, .env, and gdtest.toml. If none are set, it tries to auto-discover a compatible Godot 4 executable from common command names and common install locations.

If your binary has a different name or lives somewhere unusual, set it in gdtest.toml or via an environment variable:

# gdtest.toml
godot_exe = "godot4"   # or an absolute path

# or export once in your shell / .env file
GODOT_EXE=/path/to/godot4

Requires Godot 4.0+.

4. Write a test

Create test/test_battle.gd:

extends GdTest

func test_basic_hit() -> void:
    assert_eq(Battle.calc_damage(10, 3), 7)

func test_crit_doubles_damage() -> void:
    assert_eq(Battle.calc_damage(10, 3, true), 14)

5. Run it

gdtest
gdtest test/
gdtest test/test_battle.gd
gdtest test/ --filter "crit"
gdtest test/ --watch

6. Optional config

# gdtest.toml
harness = "addons/gdtest/gdtest_worker.gd"

[profile.ci]
reporter = "junit"
fail_fast = true
jobs = 4

gdtest test/ --profile ci

See Configuration for the full file format.

Next: Writing Your First Test