Command Line
Also supplied in this repo is the gut_cmdln.gd script that can be run from the command line. This is also used by the VSCode Plugin gut-extension.
Note: All the examples here come from my Mac/Bash.
In the examples below I will be using godot as a command. This is an alias I have created as:
alias godot='/Applications/Godot.app/Contents/MacOS/Godot'
From the command line, at the root of your project, use the following command to run the script. Use the options below to run tests.
godot -d -s --path "$PWD" addons/gut/gut_cmdln.gd
The -d option tells Godot to run in debug mode which is helpful. The -s option tells Godot to run a script. --path "$PWD" tells Godot to treat the current directory as the root of a project.
When running from command line, 0 will be returned if all tests pass and 1 will be returned if any fail (pending doesn’t affect the return value).
Options
Output from the command line help via -gh option
The GUT CLI
-----------
The default behavior for GUT is to load options from a res://.gutconfig.json if
it exists. Any options specified on the command line will take precedence over
options specified in the gutconfig file. You can specify a different gutconfig
file with the -gconfig option.
To generate a .gutconfig.json file you can use -gprint_gutconfig_sample
To see the effective values of a CLI command and a gutconfig use -gpo
Values for options can be supplied using:
option=value # no space around "="
option value # a space between option and value w/o =
Options whose values are lists/arrays can be specified multiple times:
-gdir=a,b
-gdir c,d
-gdir e
# results in -gdir equaling [a, b, c, d, e]
To not use an empty value instead of a default value, specifiy the option with
an immediate "=":
-gconfig=
Usage
-----------
<path to godot> -s addons/gut/gut_cmdln.gd [opts]
Options
-----------
Test Config:
-gdir List of directories to search for test scripts in.
-ginclude_subdirs Flag to include all subdirectories specified with -gdir.
-gtest List of full paths to test scripts to run.
-gprefix Prefix used to find tests when specifying -gdir. Default "test_".
-gsuffix Test script suffix, including .gd extension. Default ".gd".
-gconfig The config file to load options from. The default is res://.gutconfig.json.
Use "-gconfig=" to not use a config file.
-gpre_run_script pre-run hook script path
-gpost_run_script post-run hook script path
-gerrors_do_not_cause_failure When an internal GUT error occurs tests will fail. With this option
set, that does not happen.
-gdouble_strategy Default strategy to use when doubling. Valid values are [INCLUDE_NATIVE,
SCRIPT_ONLY]. Default "SCRIPT_ONLY"
Run Options:
-gselect All scripts that contain the specified string in their filename will be ran
-ginner_class Only run inner classes that contain the specified string in their name.
-gunit_test_name Any test that contains the specified text will be run, all others will be skipped.
-gexit Exit after running tests. If not specified you have to manually close the window.
-gexit_on_success Only exit if zero tests fail.
-gignore_pause Ignores any calls to pause_before_teardown.
-gno_error_tracking Disable error tracking.
-gfailure_error_types Error types that will cause tests to fail if the are encountered during
the execution of a test. Default "["engine", "gut", "push_error"]"
Display Settings:
-glog Log level [0-3]. Default 1
-ghide_orphans Display orphan counts for tests and scripts. Default false.
-gmaximize Maximizes test runner window to fit the viewport.
-gcompact_mode The runner will be in compact mode. This overrides -gmaximize.
-gopacity Set opacity of test runner window. Use range 0 - 100. 0 = transparent,
100 = opaque.
-gdisable_colors Disable command line colors.
-gfont_name Valid values are: ["AnonymousPro", "CourierPrime", "LobsterTwo", "Default"].
Default "CourierPrime"
-gfont_size Font size, default "16"
-gbackground_color Background color as an html color, default "262626ff"
-gfont_color Font color as an html color, default "ccccccff"
-gpaint_after Delay before GUT will add a 1 frame pause to paint the screen/GUI. default 0.1
-gwait_log_delay Delay before GUT will print a message to indicate a test is awaiting
one of the wait_* methods. Default 0.5
Result Export:
-gjunit_xml_file Export results of run to this file in the Junit XML format.
-gjunit_xml_timestamp Include a timestamp in the -gjunit_xml_file, default false
Help:
-gh Print this help. You did this to see this, so you probably understand.
-gpo Print option values from all sources and the value used.
-gprint_gutconfig_sample Print out json that can be used to make a gutconfig file.
Examples
Run godot in debug mode (-d), run a test script (-gtest), set log level to lowest (-glog), exit when done (-gexit)
godot -s addons/gut/gut_cmdln.gd -d --path "$PWD" -gtest=res://test/unit/sample_tests.gd -glog=1 -gexit
Load all test scripts that begin with ‘me_’ and end in ‘.res’ and run me_only_only_me.res (given that the directory contains the following scripts: me_and_only_me.res, me_only.res, me_one.res, me_two.res). I don’t specify the -gexit on this one since I might want to run all the scripts using the GUI after I run this one script.
godot -s addons/gut/gut_cmdln.gd -d --path "$PWD" -gdir=res://test/unit -gprefix=me_ -gsuffix=.res -gselect=only_me
Config file
To cut down on the amount of arguments you have to pass to gut and to make it easier to change them, you can optionally use a json file to specify some of the values. By default gut_cmdln looks for a config file at res://.gutconfig.json. You can specify a different file using the -gconfig option.
Here is a sample file. You can print out the text for a gutconfig file using the -gprint_gutconfig_sample option.
Example
{
"dirs":["res://test/unit/","res://test/integration/"],
"double_strategy":"partial",
"ignore_pause":false,
"include_subdirs":true,
"inner_class":"",
"log_level":3,
"opacity":100,
"prefix":"test_",
"selected":"",
"should_exit":true,
"should_maximize":true,
"suffix":".gd",
"tests":[],
"unit_test_name":"",
}
Common Errors
I really only know of one so far, but if you get a space in your command somewhere, you might see something like this:
ERROR: No loader found for resource: res://samples3
At: core\io\resource_loader.cpp:209
ERROR: Failed loading scene: res://samples3
At: main\main.cpp:1260
I got this one when I accidentally put a space instead of an “=” after -gselect.