Command Line Tool

GdUnit3 Command Line Tool

GdUnit3 provides a tool that allows you to run a specific set of test suites and tests from the command line. The tool is named runtest.sh for linux/macos and runtest.cmd for windows and is located in the project folder and provides a set of commands. To get an overview of the available commands, execute it with the command -help.

----------------------------------------------------------------------------------------------
 GdUnit3 Comandline Tool

 Usage:
        runtest -a <directory|path of testsiute>
        runtest -a <directory> -i <path of testsuite|testsuite_name|testsuite_name:test_name>

-- Options ---------------------------------------------------------------------------------------

  [-help]                                 Shows this help message.

  [--help-advanced]                       Shows advanced options.

  [-a, --add]                             Adds the given test suite or directory to the execution pipeline.
     -a <directory|path of testsuite>

  [-i, --ignore]                          Adds the given test suite or test case to the ignore list.
     -i <testsuite_name|testsuite_name:test-name>

  [-c, --continue]                        By default GdUnit will abort on first test failure to be fail fast, instead of stop after first failure you can use this option to run the complete test set.

  [-conf, --config]                       Run all tests by given test configuration. Default is 'GdUnitRunner.cfg'
     -conf [testconfiguration.cfg]

Preconditions to run on Windows 10

Setup test environment as follow

Add the environment variable GODOT_BIN by open a termial and enter the command. Replace the path D:\develop\Godot.exe with your own location where you have Godot installed.
```
  setx GODOT_BIN D:\develop\Godot.exe
```
The GdUnit tool uses colored console output and needs to be enabled manually under Windows 10.

Do it manually by open regedit:

The registry key at HKEY_CURRENT_USER\Console\VirtualTerminalLevel sets the global default behavior for processing ANSI escape sequences. Create a
DWORD key (if necessary) and set its value to 1 to globally enable (or 0 to disable`) ANSI processing by default.

Do this with the following command and open the terminal again:
```
REG ADD HKCU\CONSOLE /f /v VirtualTerminalLevel /t REG_DWORD /d 1
```

Now you can run your tests by runtest [cmd]

Preconditions to run on MacOS

setup test environment as follow

Add the environment variable GODOT_BIN by open a termial and enter the command. Replace the path /Applications/Godot.app/Contents/MacOS/Godot with your own location where you have Godot installed.
```
 export GODOT_BIN=/Applications/Godot.app/Contents/MacOS/Godot
```

Now you can run your tests by ./runtest.sh [cmd]

How to use

Please note the requirements described above!

You can use the tool to run a complete test package or only a specific set of execution definitions or tests.

    # runs all testsiutes located under the directory '/myProject/test'
    testrun -a /myProject/test

You can specify one ore more directories for execution

    # runs all testsiutes located under the directory /myProject/test/foo/bar1' and '/myProject/test/foo/bar3'
    testrun -a /myProject/test/foo/bar1 -a /myProject/test/foo/bar3

Sometimes it may be necessary to skip (ignore) some test suites or tests from test execution.

You can do this easily with the command ‘-i’.

    # runs all testsiutes located under the directory /myProject/test' exclusive all tests located under '/myProject/test/foo/bar3'
    testrun -a /myProject/test -i /myProject/test/foo/bar3

You can also specify skipping by testsuite name and/or testcase name.

    # runs all testsiutes located under the directory /myProject/test' exclusive testsuite 'ClassATest' and 'ClassBTest:test_abc'
    testrun -a /myProject/test -i ClassATest -i ClassBTest:test_abc

You can also rerun the latest test execution (executed over the UI GdUnit-inspector)

    # loads latest GdUnitRunner.cfg and runs the configured tests
    testrun -conf

    # loads a specific test configuration and runs the configured tests (since v1.0.6)
    testrun -conf <test_config.cfg>

The report is stored by default under /reports. You can also change the default report directory invidually with the option -rd [directory]. By default, the last 20 reports are saved, older reports are automatically deleted. You can change the number with -rc [number].

See next section.

Advanced Options

You can control the created reports by advanced options.

 [-rd, --report-directory]               Specifies the output directory in which the reports are to be written. The default is res://reports/.
    -rd <directory>

 [-rc, --report-count]                   Specifies how many reports are saved before they are deleted. The default is 20.
    -rc <count>

To get an overview of all advaced options use --help-advanced.

Return Codes

The tool ends with a certain return code, where you can check if the tests were completed successfully.

 = all tests success
= ends with test failures
= ends with test warnings

The Report

The GdUnit command line tool generates a modern HTML and JUnit report with which you can quickly get an overview of the executed tests. You can find the reports in the report folder as:

index.htm - the HTML report
results.xml - the JUnit report

The HTML report

Report by Path

You can switch between the full list of executed test-suites or the view collected by paths. If you click on a test-suite you can view the report for a specific test-suite.

Select a Testsuite Report

By further selecting the test cases, the test errors can be viewed in the “Failure Report” window.

Logging

If logging is enabled in your project, the report saves the current log and can be viewed by clicking Logging.