Your first 10 minutes
Run a first check, fix what it finds, and write your first test.
This page follows a tiny game, with a player.gd and a hud.gd, through its
first check. Do the same on your own project: the problems will differ, the
steps are the same.
You need GDSuite installed. There is nothing to set up in the project.
Run a check
In a terminal, in your project's folder:
gdsuite checkThe check runs four steps in order (formatting, lint, type check, code health) and stops at the first one that finds something:
error: Formatting issues found (fmt, 10ms)
hud.gd: would be reformatted
player/player.gd: would be reformatted
Found formatting issues in 2 files. Run `gdsuite fmt` to format the target.
error: check failedDon't worry about a long list on an existing project: most of it fixes itself in the next step.
Let GDSuite format your scripts
gdsuite fmtThis rewrites the layout of your scripts (spaces, indentation, blank lines) to follow Godot's style guide. It never changes what the code does: GDSuite checks every file it rewrites and leaves it alone if anything else would change. If your project uses Git, commit before, so you can review the change.
Fix what the linter finds
Run the check again. Formatting passes; now the linter speaks:
pass: Formatting check passed (fmt, 10ms)
error: Lint check failed (lint, 9ms)
player/player.gd:2:1 [class-definitions-order] Definition out of order in global scope: `classnames` must come before `extends`
player/player.gd:15:1 [class-definitions-order] Definition out of order in global scope: `signals` must come before `others`
Found 2 lint problems. Fix them and rerun `gdsuite check`.
error: check failedEach line gives the file, the line and column, the rule in brackets, and what
is wrong. Here, the style guide wants class_name before extends, and
signals at the top of the script. Move them, and run the check again.
A rule you disagree with can be turned off for the whole project. Linting explains how →
Fix the errors Godot would have shown
pass: Formatting check passed (fmt, 10ms)
pass: Lint check passed (lint, 9ms)
error: GDScript type check failed (typecheck, 290ms)
hud.gd:10: error[missing-resource]: "res://levels/level_2.tscn" does not exist
gdtypecheck: 1 error(s), 0 warning(s) (3 scripts)
Found 1 error. Fix it and rerun `gdsuite check`.
error: check failedhud.gd loads a level that was renamed. The game would only have crashed
when a player reached the exit. Fix the path, and check again:
pass: Formatting check passed (fmt, 10ms)
pass: Lint check passed (lint, 9ms)
pass: GDScript type check passed (typecheck, 289ms)
pass: Health checks passed (health, 78ms)Everything passes. Run gdsuite check whenever you finish a change, before
you commit.
Write your first test
A test is a small script that uses a piece of your game and checks the
result. Create test/test_player.gd:
extends GdTest
func test_damage_lowers_health() -> void:
var player := Player.new()
player.take_damage(30)
assert_eq(player.health, 70)
player.free()
func test_health_never_goes_below_zero() -> void:
var player := Player.new()
player.take_damage(500)
assert_eq(player.health, 0)
player.free()Each function whose name starts with test_ is one test. assert_eq checks
that the first value equals the second. Run the tests:
gdsuite test✓ res://test/test_player.gd :: test_health_never_goes_below_zero (16 µs)
✓ res://test/test_player.gd :: test_damage_lowers_health (11 µs)
2 tests 2 passedNow if someone changes take_damage and health can go negative, the second
test turns red and tells you, long before a player finds it.
Use GDSuite from the Godot editor
Your first gdsuite test also installed the GDSuite addon for the editor:
- Open your project in Godot.
- Go to Project → Project Settings → Plugins and turn on GDSuite.
- A Check button appears in the top bar, and a Problems dock lists what the check finds; double-click a problem to open its line. A Tests dock lists your tests: run all of them, one file, or one test, and double-click a failure to open the script at the right line.
Where next
- Learn what each step of the check does, starting with Formatting.
- Write more tests: Your first test goes further.
- Working with others? Run GDSuite in CI so every change is checked.