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 are no longer runnable -- the GUT compatibility bridge was removed in v0.6.0; run gd-tools migrate to move them onto GdToolsTest.

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 GUT compatibility bridge was removed in v0.6.0: suites extending GutTest are no longer runnable -- gd-tools test rejects them with exit 2 and migration guidance. Run gd-tools migrate and see the migration guide for 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
gd-tools test --parallel 4                 # run suites with 4 concurrent workers
gd-tools test --changed                    # only suites mapped from git-changed files
gd-tools test --changed --base main        # PR/CI mode: diff from merge-base with main

--tag is repeatable, and --test-timeout (per test) is separate from --timeout (per suite process). --parallel dispatches suites to a bounded worker pool (1-32 workers; bare --parallel means 4) while keeping results, JUnit XML, and merged coverage identical to a sequential run. Persist the choice with parallel = 4 under [test] in gd-tools.toml.

--changed selects suites from git instead of running everything: uncommitted changes (staged, unstaged, and untracked) map to suites by the same file→suite convention as --watch — src/enemy.gd selects tests/test_enemy.gd or tests/enemy_test.gd. A change that maps to no suite (e.g. project.godot or a scene file) falls back to the full suite with an explicit notice, so the selection is safe for CI. The summary line reports how many suites were selected; per-file mapping detail prints under --verbose. Add --base <ref> to diff committed changes from merge-base(<ref>, HEAD) instead of the working tree — the form to use on pull-request CI. --changed composes with --parallel, --coverage, and the --suite/--test/--tag filters (the active filters bound the mapping domain); an empty change set exits 0 without launching Godot.

Repeat runs are faster: the godot --headless --import step is cached under .gd-tools/native/import-cache/ and skipped when project.godot, any project source/resource file (scripts, scenes, import sidecars, addons), or the Godot version is unchanged. The integration preflight is likewise cached under .gd-tools/native/preflight-cache/ and skipped when the suites, test files, project.godot, Godot version, and bundled addons are unchanged. Cache hit/miss reasons are reported under --verbose; --no-cache bypasses the import, preflight, and coverage plan caches, and gd-tools clean --cache removes the cache directory.

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. The same file→suite mapping powers the non-interactive gd-tools test --changed selection (see Selecting and Filtering Tests).

• Native runtime only: the removed legacy GUT runtime (--runtime gut) is rejected with exit 2; GutTest suites must be migrated (gd-tools migrate).
• Interactive only: --watch combined with CI=true exits 2.
• The terminal is cleared between runs; the banner shows how many files are watched. While idle, Ctrl+C exits 0; interrupting an in-flight run kills its Godot processes and exits 130.
• 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).

Migrating Legacy GUT Suites

The GUT compatibility bridge was removed in v0.6.0; the native runtime (GdToolsTest) is the only supported runtime. Suites extending GutTest are rejected by gd-tools test with exit 2 and migration guidance, and --runtime gut is rejected the same way. Run gd-tools migrate and see the migration guide to move legacy suites onto the native runtime.

Known limitations. Parallel execution is opt-in and off by default (--parallel N / [test].parallel); suites run sequentially without it. See the 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 any runtime
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
# parallel = 4            # opt-in parallel suite execution (1-32; unset runs sequentially)
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"]

Editor Autocomplete & Validation

gd-tools publishes a JSON Schema for gd-tools.toml at docs/gd-tools.schema.json. Add a "$schema" key to your config to enable autocomplete and inline validation in editors that support TOML schemas:

"$schema" = "https://raw.githubusercontent.com/mansyar/gd-tools/main/docs/gd-tools.schema.json"

The key is accepted and ignored by the CLI — it carries no runtime meaning.

• VS Code (with Even Better TOML): the "$schema" key above is picked up automatically. Alternatively, associate the schema by filename in your settings: "even-better-toml.schema.associations": {"gd-tools.toml": "https://raw.githubusercontent.com/mansyar/gd-tools/main/docs/gd-tools.schema.json"}
• taplo (CLI / LSP): the "$schema" key works out of the box, or add a schema entry to your taplo.toml pointing at the URL above.

The schema is regenerated with gd-tools config schema --output docs/gd-tools.schema.json; a unit test keeps the checked-in snapshot in sync with the installed version's config model.

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 informed the native runtime's assertion surface.
• 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.