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:
- Open the project in Godot.
- 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]ingdsuite.toml, asgdsuite checkdoes. 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 toproject.godotor 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:
| Setting | Default | What it does |
|---|---|---|
| Format on save | Off | Formats the script when you save it |
| Lint on save | On | Lints the script you saved, and updates its problems |
| Type check after saving | On | Type checks the project a moment after you save, in the background |
| Watch: run the affected tests on save | Off | Runs the tests a saved file affects; also the Watch button of the Tests dock |
| Show problems in the script editor | On | The 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 = trueA 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.