gd-tools

A modern development workflow CLI for GDScript projects in Godot 4.5+.

1. Overview

gd-tools brings professional development tooling to GDScript -- test, lint, format, and code coverage in a single CLI. It wraps gdtoolkit for linting and formatting, runs its own Godot-native test runtime, and fills the remaining gap with a custom hybrid coverage system -- production-quality line and branch coverage for GDScript that no existing tool provides.

Tests are written against GdToolsTest, a native GDScript base class that runs inside your Godot project, so a test can touch the real scene tree, await real signals, and assert on real engine objects without leaving the engine. Existing suites that extend GutTest run through the built-in compatibility bridge -- no GUT addon required -- while projects migrate. The bridge is deprecated as of v0.5.0 and will be removed in v0.6.0.

One install, one config, one mental model.

2. Features

3. Installation

pip install gd-tools-cli

gd-tools requires Python 3.10+ and a Godot 4.5+ binary on your system. The Godot binary is auto-detected from configuration, environment variables (GODOT_BIN, GODOT4_BIN, GODOT_PATH), PATH, or common install locations.

4. Quick Start

# 1. Install
pip install gd-tools-cli

# 2. Bootstrap your Godot project
cd your-godot-project
gd-tools init

# 3. Run your tests
gd-tools test

# 4. Run tests with coverage
gd-tools test --coverage --min 80

# 5. Show uncovered lines and branches when coverage is below 100%
gd-tools test --coverage --show-uncovered

# 6. Force plan regeneration, bypassing the coverage plan cache
gd-tools test --coverage --no-cache

gd-tools init deploys the native test addon and the coverage addon, generates gd-tools.toml, gdlintrc, and gdformatrc, and creates the .gd-tools/ directory. The command is idempotent -- safe to re-run. If you've modified coverage addon files, they are automatically backed up to addons/gd-tools-coverage/.backups/ before being overwritten.

The legacy GUT runtime has been replaced by the built-in compatibility bridge: suites extending GutTest run on the native runtime with no GUT addon installed. The bridge is deprecated as of v0.5.0 and will be removed in v0.6.0. See the migration guide for the supported subset and the steps to move fully onto GdToolsTest.

A test suite is any class extending GdToolsTest:

extends GdToolsTest

func test_health_starts_at_full() -> void:
    assert_eq(health.current(), 100)

5. CLI Command Summary

Selecting and Filtering Tests

gd-tools test                              # every discovered suite
gd-tools test --suite PlayerTests          # one suite, by class name
gd-tools test --test test_takes_damage     # one test method
gd-tools test --tag smoke                  # suites with that class-level tag
gd-tools test --test-timeout 30            # per-test timeout, in seconds

--tag is repeatable, and --test-timeout (per test) is separate from --timeout (per suite process).

Each run writes a machine-readable artifact index under .gd-tools/artifacts/<run_id>/, listing the manifest, result, event stream, engine log, coverage data, and any failure screenshots the run actually produced. Only the latest run is retained. See the User Guide for the full artifact tree.

Watch Mode

gd-tools test --watch                      # watch .gd files, re-run on change
gd-tools test --watch --coverage           # every re-run includes coverage
gd-tools test --watch --tag smoke          # filters apply to every run

--watch runs the full suite once, then keeps watching: saving a .gd file re-runs the tests affected by the change. The changed file is mapped to its suite by convention — src/enemy.gd re-runs tests/test_enemy.gd or tests/enemy_test.gd — with a full-suite fallback (announced explicitly) when no suite matches. Rapid successive saves are coalesced into a single re-run, and a save during a running suite queues exactly one follow-up run.

• Native runtime only: the removed legacy GUT runtime (--runtime gut) is rejected with exit 2; GutTest suites run through the compatibility bridge.
• Interactive only: --watch combined with CI=true exits 2.
• The terminal is cleared between runs; the banner shows how many files are watched, and Ctrl+C always exits 0.
• Positional path arguments are not supported with --watch; the watched scope is the project root minus standard excludes (.godot/, .gd-tools/, .git/, and the gd-tools addons).

Native Runtime vs. GUT Compatibility Bridge

The native runtime is the default and the forward path. Suites extending GutTest run through the built-in compatibility bridge on the same native runner; the bridge is deprecated as of v0.5.0 and will be removed in v0.6.0.

Known limitations. Parameterized tests are native-only -- the bridge deliberately refuses parameterize() at preflight rather than mis-running them, so such suites must migrate to GdToolsTest. Suites run sequentially; parallel execution is planned but not yet available. The bridge itself is deprecated as of v0.5.0 and will be removed in v0.6.0. See the migration guide for the bridge's supported subset, User Guide for the full flag reference, and Roadmap for what is planned.

Verbosity Control

gd-tools supports two global flags that control output verbosity. Place them before the subcommand:

The flags are mutually exclusive -- using both exits with code 2.

# Verbose: see the Godot command and elapsed time
gd-tools --verbose test

# Quiet: minimal output for CI pipelines
gd-tools --quiet lint
gd-tools --quiet doctor

# Default: current behavior (no change)
gd-tools test

Always shown (regardless of flag): test pass/fail summaries, lint violations, coverage reports, error messages, and exit codes.

See the User Guide for full command reference, flags, examples, and exit codes.

6. Shell Completion

gd-tools supports tab completion for bash, zsh, fish, and PowerShell. Generate a completion script with gd-tools completion <shell> and source it in your shell configuration.

Bash:

# Add to ~/.bashrc or ~/.bash_profile
eval "$(gd-tools completion bash)"

Zsh:

# Add to ~/.zshrc
eval "$(gd-tools completion zsh)"
# Or save to a file in your fpath:
gd-tools completion zsh > ~/.zsh/completions/_gd-tools

Fish:

gd-tools completion fish > ~/.config/fish/completions/gd-tools.fish

PowerShell:

gd-tools completion powershell | Out-String | Add-Content $PROFILE

Alternative -- Click's environment variable:

Click also supports completion via the _GD_TOOLS_COMPLETE environment variable. This is useful for advanced users who prefer not to modify their shell profile:

# Bash example
export _GD_TOOLS_COMPLETE=bash_source
eval "$(gd-tools)"

See the User Guide for detailed per-shell instructions.

7. Configuration

gd-tools uses a single gd-tools.toml file as the source of truth for all tool configuration. gd-tools init generates this file with sensible defaults.

[godot]
binary = ""  # Optional -- auto-detected if unset

[test]
test_dirs = ["test", "tests"]
prefix = "test_"
suffix = ".gd"
gutconfig = ".gutconfig.json"  # legacy; not read by the native runtime or the bridge
runtime = "native"        # native (default); "gut" is no longer a runnable runtime
timeout_seconds = 5.0     # default per-test timeout for async native tests
retries = 0               # opt-in retries per native test
tags = []                 # native suite tag filters

[lint]
exclude = ["addons", ".godot", ".gd-tools", ".git"]

[format]
exclude = ["addons", ".godot", ".gd-tools", ".git"]

[coverage]
enabled = false
min_percent = 0
format = "html"  # html, lcov, cobertura, text
output_dir = ".gd-tools/coverage"
exclude = ["addons", ".godot", ".gd-tools", ".git"]
test_dirs = ["test", "tests"]

See the User Guide for a full configuration reference with all keys, defaults, and examples.

8. Documentation

9. Development

# Clone and install in editable mode with dev dependencies
git clone https://github.com/mansyar/gd-tools.git
cd gd-tools
pip install -e ".[dev]"

Running Tests

Unit tests run without Godot. Integration tests require a Godot 4.5+ binary -- configure via .env (see .env.example):

cp .env.example .env
# Edit .env: set GODOT_BIN to your Godot binary path

# Run all tests with coverage
CI=true pytest

CI=true is what makes a missing Godot binary a failure rather than a skip. Without it, integration and end-to-end tests skip quietly when Godot is absent, so a run can report success having executed nothing.

See Testing Strategy for the full testing guide and Contributing Guide for development setup details.

10. License

MIT

11. Acknowledgements

gd-tools stands on the shoulders of two excellent community tools. It wraps them; it does not replace them. Full credit to their authors for the hard parts.

• GUT (Godot Unit Test) by bitwes: the GDScript test framework whose core API the built-in compatibility bridge reproduces while projects migrate to the native runtime.
• gdtoolkit by Scony: provides gdlint and gdformat, which gd-tools lint and gd-tools format wrap.

The native test runtime (GdToolsTest) and the custom hybrid coverage system (plan generation, runtime instrumentation, and reporting) are the original work of gd-tools and fill the gaps these tools do not cover.