GDSuite Docs

In the Godot editor

Check the project, see its problems on the right lines, format scripts, and run tests without leaving Godot.

GDSuite comes with an addon for the Godot editor. It runs the same checks as gdsuite check, with the same gdsuite.toml, so what is green in the editor is green in the terminal and in CI.

Turn it on

The first gdsuite test (or gdsuite init) puts the addon in addons/gdsuite/. Commit it with the rest of the project. Then, once:

  1. Open the project in Godot.
  2. Go to Project → Project Settings → Plugins and turn on GDSuite.

The addon runs the gdsuite program you installed: it finds the one in your project's .gdsuite/ folder, or on your PATH. If it says gdsuite is not found, see Install, or set its path in Editor Settings → GDSuite → Program.

It works best with Godot 4.7 and newer; Godot 4.5 is supported.

Check the project

Two icons in the editor's top bar show where the project stands:

  • Check (a page with a tick): grey until GDSuite has looked at the project, then red when there are errors, yellow when there are only warnings, green when there are none. It counts what formatting, linting and the type check found, as listed in the Problems dock. Click it to run the project's check: the steps of [check] in gdsuite.toml, as gdsuite check does. Its tooltip then lists each step:

    ✔ fmt: format check passed
    ✖ lint: 1 lint problem in 4 files
  • Tests (a flask): red when a test fails, green when every test ran and passes, grey when some tests have not run yet or must run again because a script changed. Click it to run all tests.

The Problems dock

The Problems dock lists what linting and the type check found, and the scripts that are not formatted, grouped by script:

  • Double-click a problem to open the script at its line.
  • Errors, Warnings, Format, Lint and Types filter the list; a filter that is off is faded. Whole project or Current script chooses which scripts it shows.
  • Right-click a lint problem to fix it (when it can be fixed), ignore it on this line, turn its rule off for the whole project (written in gdsuite.toml), or read what the rule means. Right-click a script that is not formatted to format it.
  • Drag the edge of the Where or Rule column to make it wider or narrower; the widths are kept for the project.

The list shows the whole project, including problems in scripts you haven't opened: a broken reference in a scene, a script loading a file that was renamed. Godot's own warnings and errors are in it too, so a problem doesn't disappear from the list when you open its script.

Like any dock, you can move it to a side, or make it a window of its own.

Problems in the script editor

In the script you're editing, a line with a problem gets an icon in the margin and a light red or yellow tint. Click the icon to read the problem.

Format a script

Format script formats the script you're editing, with the project's formatting settings, even before you save it. It's one step to undo with Ctrl+Z.

Run it from:

  • Project → Tools → GDSuite → Format script,
  • the command palette (Ctrl+Shift+P, then "Format Script"),
  • Shift+Alt+F, which you can change in Editor Settings → Shortcuts.

A script with a syntax error is left as it is.

Run tests

The Tests dock lists the project's tests: the ones gdsuite test runs, from the folder in [commands] default_test_target.

  • Run all runs every test; while tests run, it becomes Stop.
  • Run failed runs again the tests that failed, and says how many.
  • The ▶ at the end of each row runs that script or that test. Right-click runs the selected tests, and double-click opens a test.
  • Watch runs tests again when you save a script, a scene or a resource: only the tests that use it, directly or through other scripts, scenes and resources (extends, preload/load, class_name, autoloads), and the scenes they were seen loading when they last ran. A test script runs its own tests; a change to project.godot or an autoload runs them all. See what a change affects.
  • Search tests keeps the tests whose name or script matches.
  • ✖ failed, ✔ passed and 🕑 to run count the tests of each kind; click one to hide those tests, or show them again. "To run" are the tests not run yet, and those whose scripts changed since they ran.
  • Select a test that failed to read why.

While tests run, a bar under the buttons fills, green, or red once a test failed, and the count shows where the run is (Running 120 / 358, 2 failed). Each test shows where it is: a clock while it waits, a spinner while it runs, then its result. The tests of the last run have a tinted row; a test that has not run, or whose script changed since it ran, is faded. The list keeps its order, and what you unfolded stays unfolded.

The Time column shows how long each test took, and each script the time of its tests. Click its title to put the slowest first, and the Test title to sort by name again. Drag its edge to resize it.

In the script editor, a test script gets a ▶ next to each test. Click it to run that test; after a run, it shows whether the test passed. Folders and scripts in the FileSystem dock have Run Tests in their right-click menu.

The command palette has Run All Tests, Rerun Failed Tests and Run Tests in Script.

Tests run in the background with the Godot of your editor, as gdsuite test runs them, so they don't stop you from working. They run in parallel: one Godot per processor core, each taking the next test waiting.

If you used the gdtest panel before (addons/gdtest_editor/), gdsuite test removes it: the Tests dock replaces it. If you changed its files, they are kept and you can delete the folder.

When you save

What runs when you save a script is your choice. Turn each one on or off from the ⚙ button of the Problems dock, or in Editor Settings → GDSuite:

SettingDefaultWhat it does
Format on saveOffFormats the script when you save it
Lint on saveOnLints the script you saved, and updates its problems
Type check after savingOnType checks the project a moment after you save, in the background
Watch: run the affected tests on saveOffRuns the tests a saved file affects; also the Watch button of the Tests dock
Show problems in the script editorOnThe icons and tints in the script editor

These are yours: they apply to every project on your computer.

The same choice for the whole team

To make everyone format on save, say so in the project's gdsuite.toml:

[editor]
format_on_save = true

A setting in [editor] wins over each person's own; the ⚙ menu shows it as "set by this project". The keys are format_on_save, lint_on_save, type_check_on_save and run_tests_on_save.

Your changes to the addon

gdsuite updates addons/gdsuite/ when you update gdsuite. A file of the addon you changed is kept as it is: delete it to get the new version.