GDSuite Docs

Filters, tags and coverage

Choose which tests run, tag them, measure coverage, benchmark, and check your suite with mutation testing.

In a GDSuite project

The commands on this page call gdtest directly. GDSuite installs gdtest for you and passes it the same arguments: gdtest <arguments> becomes gdsuite test -- <arguments>.

Every flag below is listed in the CLI Reference.

Choosing what runs

gdtest                                   # every test the discovery globs find
gdtest test/combat/                      # one folder
gdtest test/test_player.gd               # one file
gdtest test/test_player.gd::test_jump    # one test
gdtest --filter "inventory"              # tests whose `file :: func` matches a regex
gdtest --list                            # print what would run, run nothing

Only what your change affects

gdtest --changed-only                 # uncommitted changes (git diff HEAD)
gdtest --changed-since origin/main    # everything changed on your branch
gdtest --affected-by res://src/player.gd          # the tests a file can affect
gdtest --affected-by res://src/player.gd --list   # which ones, without running them

gdtest builds the dependency graph of the project and runs the test files that reach a changed file. A file uses:

  • in a script: what it extends, preloads or loads, any other "res://…" or "uid://…" string, another script's class_name and an autoload it names;
  • in a scene or a .tres resource: its ext_resources.

A test file reaches the files it uses, the files those use, and so on. A change to a scene reruns the tests that use the scene, and the tests of the scripts in it.

Some changes affect every test: project.godot, gdtest.toml, an autoload, and the gdtest addon. Files opened with FileAccess or DirAccess are not followed, unless a "res://…" string names them: they are mostly saves and logs.

gdtest also learns from the tests it runs, as Vitest learns a test's dynamic imports by running it. While a test runs, gdtest notes the scene and the script of every node it adds to the tree, and keeps them per test file in .godot/gdtest/uses.json. A test file then also depends on what it was seen using: the scenes it loaded with a computed path, and the scripts of those scenes. What a test file was seen using adds up over runs.

A script that loads a computed path, such as load(scene_path), may load any file. Until a test that reaches it has run once, that test runs on every change; gdtest names these scripts. Resources that are not nodes, such as a .tres loaded with a computed path, are not seen: say where such a script loads from with a comment, and it depends on that folder:

# gdtest: loads res://gameplay/*.tscn
func restore(data: Dictionary) -> Node:
    return load(data.scene_path).instantiate()

res://gameplay/ is every file of the folder and the folders in it; res://gameplay/*.tscn only its scenes. A string with a known folder, as load("res://items/" + id), needs no comment.

Watch mode

gdtest test/ --watch

Runs the targets, then after each change to a file of the project, the test files it can affect, as above, until Ctrl-C.

Tags

Tag a test with ## @tag lines right above it:

## @tag slow
## @tag integration
func test_full_match_simulation() -> void:
    ...
gdtest --tag integration          # only tests tagged integration
gdtest --tag fast --tag unit      # tagged fast or unit
gdtest --exclude-tag slow         # everything except slow tests

To make it the default, set include_tags or exclude_tags in the configuration, for example in a ci profile.

Focus and skip

Prefix a test with ftest_ to run only it in its file, or xtest_ to skip it. Inside a test, skip("reason") and pending("reason") mark it without failing. See Assertions Reference.

Coverage

gdtest --coverage                          # writes coverage/lcov.info
gdtest --coverage --min-coverage 80        # fail below 80% line coverage
gdtest --coverage --coverage-exclude "scripts/debug/**"

gdtest instruments your scripts for the run, merges the counts from every worker, prints a summary and writes an LCOV file that coverage services and editor extensions read.

HTML report

gdtest --html-report                 # gdtest-report.html
gdtest --html-report reports/run.html

A single file with every result and failure message, to attach to a CI run.

Property tests

Gdt.forall calls your check with generated inputs, 100 times by default. When a case fails, gdtest shrinks it to a smaller failing input and prints it with the seed:

func test_damage_never_negative() -> void:
    Gdt.forall([Gdt.gen_int(0, 1000), Gdt.gen_int(0, 1000)], func(attack: int, defense: int) -> void:
        assert_gte(Battle.calc_damage(attack, defense), 0)
    )

Re-run that exact case with gdtest --seed <seed>. Generators are listed in the Assertions Reference.

Benchmarks

Functions named bench_* are benchmarks. A normal run skips them; --bench runs only them:

func bench_pathfinding() -> void:
    var result = Gdt.bench(func() -> void: grid.find_path(start, goal), 200)
    print("median %.2f ms, p95 %.2f ms" % [result.median_ms, result.p95_ms])
    Gdt.assert_completes_in(result, 4.0)
gdtest --bench

Gdt.bench(callable, iterations = 100) returns the mean, median, p95, p99, min and max time in milliseconds. Timing assertions work in any test, see the Assertions Reference.

Mutation testing

Coverage shows which lines ran; mutation testing shows whether your tests would notice those lines being wrong.

gdtest test/ --mutate scripts/battle.gd

For each small change gdtest can make to battle.gd, such as < into <= or + into -, it runs the tests. A mutant is killed when a test fails and survives when every test still passes. The score at the end is the share of killed mutants; each survivor points at behaviour no test checks.

Each mutant is written into the source file while its tests run, and the original is restored afterwards. Commit your work first, and don't edit the file during the run. --mutate can't be combined with --watch.

CI

- name: Run gdtest
  run: gdtest test/ --profile ci --no-auto-import --reporter junit > results.xml

Split a long suite across jobs with --partition, then merge the results with gdtest aggregate, see Partitioning.