Skip to content

Command Line

Jump to bottom
Butch Wesley edited this page Dec 3, 2018 · 18 revisions

Also supplied in this repo is the gut_cmdln.gd script that can be run from the command line so that you don't have to create a scene to run your tests. One of the main reasons to use this approach instead of going through the editor is that you get to see error messages generated by Godot in the context of your running tests. You also see any print statements you put in your code in the context of all the Gut generated output. It's a bit quicker to get started and is a bit cooler if I do say so. The biggest downside is that debugging your code/tests is a little more difficult since you won't be able to interact with the editor's debugger when something blows up.

Note: All the examples here come from my Mac/Bash. I'm not sure how this works on Windows unless you are using a terminal emulator like ConEMU or something. This might work with GitBash but I haven't tested it. This should work fine in Bash on whatever else you use.

If you don't have a godot command, you'll have to make one. Here's the one I use

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 (-gh)

---  Gut  ---
---------------------------------------------------------
This is the command line interface for the unit testing tool Gut.  With this interface you can run one or more test scripts from the command line.  In order for the Gut options to not clash with any other godot options, each option starts with a "g".  Also, any option that requires a value will take the form of "-g<name>=<value>".  There cannot be any spaces between the option, the "=", or inside a specified value or godot will think you are trying to run a scene.

Options
-------
 -gtest             Comma delimited list of full paths to test scripts to run.
 -gdir              Comma delimited list of directories to add tests from.
 -gprefix           Prefix used to find tests when specifying -gdir.  Default "test_"
 -gsuffix           Suffix used to find tests when specifying -gdir.  Default ".gd"
 -gmaximize         Maximizes test runner window to fit the viewport.
 -gexit             Exit after running tests.  If not specified you have to manually close the window.
 -glog              Log level.  Default 1
 -gignore_pause     Ignores any calls to gut.pause_before_teardown.
 -gselect           Select a sccript to run initially.  The first script that was loaded using -gtest or -gdir that contains the specified string will be executed.  You may run others by interacting with the GUI.
 -gunit_test_name   Name of a test to run.  Any test that contains the specified text will be run, all others will be skipped.
 -gutloc            Full path (including name) of the gut script.  Default res://addons/gut/gut.gd
 -gh                Print this help
 -gconfig           A config file that contains configuration information.  Default is res://.gutconfig.json
 -ginner_class      Only run inner classes that contain this string
 -gopacity          Set opacity of test runner window. Use range 0 - 100. 0 = transparent, 100 = opaque.
 -gpo               Print option values from all sources and the value used, then quit.
 -ginclude_subdirs  Include subdirectories of -gdir.
---------------------------------------------------------

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.

Currently you can specify:

  • dirs An array of directories to look for test scripts.
  • should_exit True/false flag to indicate if Gut should exit upon completion.
  • ignore_pause True/false flag to indicate if Gut should ignore any "pause before teardown" calls.
  • log The log level (1-3).
  • inner_class Only run inner classes that contain this string. It is case sensitive.
  • opacity Sets the opacity of the GUI.
  • should_maximize Maximize the Gut window.
  • include_subdirs Flag to indicate if the subdirectories of dirs should be included.

Example

{
  "dirs":["res://test/unit/", "res://test/integration/"],
  "should_exit":true,
  "should_maximize":false,
  "ignore_pause":true,
  "log": 3,
  "inner_class":"LikeThis",
  "include_subdirs":true
}

Alias

Make your life easier by creating an alias that includes your most frequent options. Combined with the config file, you can get a nice and easy to use gut command. Here's the ones I use in bash on a Mac:

alias godot='/Applications/Godot.app/Contents/MacOS/Godot'
alias gut='godot --debug-collisions --path $PWD -d -s addons/gut/gut_cmdln.gd'

With this, if I want to run 'test_one.gd', I just enter

gut -gselect=test_one.gd

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.

Clone this wiki locally