chore: add GUT test framework
This commit is contained in:
xiaji
157
addons/gut/documentation/docs/Command-Line.md
Normal file
157
addons/gut/documentation/docs/Command-Line.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 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](https://marketplace.visualstudio.com/items?itemName=bitwes.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:
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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_
|
||||
```text
|
||||
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)
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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
|
||||
``` json
|
||||
{
|
||||
"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`.
|
||||
Reference in New Issue
Block a user