Unit testing

Godot Engine allows to write unit tests directly in C++. The engine integrates the doctest unit testing framework which gives ability to write test suites and test cases next to production code, but since the tests in Godot go through a different main entry point, the tests reside in a dedicated tests/ directory instead, which is located at the root of the engine source code.

Platform and target support

C++ unit tests can be run on Linux, macOS, and Windows operating systems.

Tests can only be run with editor tools enabled, which means that export templates cannot be tested currently.

Running tests

Before tests can be actually run, the engine must be compiled with the tests build option enabled (and any other build option you typically use), as the tests are not compiled as part of the engine by default:

scons tests=yes

Once the build is done, run the tests with a --test command-line option:

./bin/<godot_binary> --test

The test run can be configured with the various doctest-specific command-line options. To retrieve the full list of supported options, run the --test command with the --help option:

./bin/<godot_binary> --test --help

Any other options and arguments after the --test command are treated as arguments for doctest.


Tests are compiled automatically if you use the dev_mode=yes SCons option. dev_mode=yes is recommended if you plan on contributing to the engine development as it will automatically treat compilation warnings as errors. The continuous integration system will fail if any compilation warnings are detected, so you should strive to fix all warnings before opening a pull request.

Filtering tests

By default, all tests are run if you don't supply any extra arguments after the --test command. But if you're writing new tests or would like to see the successful assertions output coming from those tests for debugging purposes, you can run the tests of interest with the various filtering options provided by doctest.

The wildcard syntax * is supported for matching any number of characters in test suites, test cases, and source file names:

Filter options












For instance, to run only the String unit tests, run:

./bin/<godot_binary> --test --test-case="*[String]*"

Successful assertions output can be enabled with the --success (-s) option, and can be combined with any combination of filtering options above, for instance:

./bin/<godot_binary> --test --source-file="*test_color*" --success

Specific tests can be skipped with corresponding -exclude options. As of now, some tests include random stress tests which take a while to execute. In order to skip those kind of tests, run the following command:

./bin/<godot_binary> --test --test-case-exclude="*[Stress]*"

Writing tests

Test suites represent C++ header files which must be included as part of the main test entry point in tests/test_main.cpp. Most test suites are located directly under tests/ directory.

All header files are prefixed with test_, and this is a naming convention which the Godot build system relies on to detect tests throughout the engine.

Here's a minimal working test suite with a single test case written:


#include "tests/test_macros.h"

namespace TestString {

TEST_CASE("[String] Hello World!") {
    String hello = "Hello World!";
    CHECK(hello == "Hello World!");

} // namespace TestString

#endif // TEST_STRING_H

The tests/test_macros.h header encapsulates everything which is needed for writing C++ unit tests in Godot. It includes doctest assertion and logging macros such as CHECK as seen above, and of course the definitions for writing test cases themselves.

See also

tests/test_macros.h source code for currently implemented macros and aliases for them.

Test cases are created using TEST_CASE function-like macro. Each test case must have a brief description written in parentheses, optionally including custom tags which allow to filter the tests at run-time, such as [String], [Stress] etc.

Test cases are written in a dedicated namespace. This is not required, but allows to prevent naming collisions for when other static helper functions are written to accommodate the repeating testing procedures such as populating common test data for each test, or writing parameterized tests.

Godot supports writing tests per C++ module. For instructions on how to write module tests, refer to Writing custom unit tests.


A list of all commonly used assertions used throughout the Godot tests, sorted by severity.




Test if condition holds true. Fails the entire test immediately if the condition does not hold true.


Test if condition does not hold true. Fails the entire test immediately if the condition holds true.


Test if condition holds true. Marks the test run as failing, but allow to run other assertions.


Test if condition does not hold true. Marks the test run as failing, but allow to run other assertions.


Test if condition holds true. Does not fail the test under any circumstance, but logs a warning if something does not hold true.


Test if condition does not hold true. Does not fail the test under any circumstance, but logs a warning if something holds true.

All of the above assertions have corresponding *_MESSAGE macros, which allow to print optional message with rationale of what should happen.

Prefer to use CHECK for self-explanatory assertions and CHECK_MESSAGE for more complex ones if you think that it deserves a better explanation.


The test output is handled by doctest itself, and does not rely on Godot printing or logging functionality at all, so it's recommended to use dedicated macros which allow to log test output in a format written by doctest.




Prints a message.


Marks the test as failing, but continue the execution. Can be wrapped in conditionals for complex checks.


Fails the test immediately. Can be wrapped in conditionals for complex checks.

Different reporters can be chosen at run-time. For instance, here's how the output can be redirected to a XML file:

./bin/<godot_binary> --test --source-file="*test_validate*" --success --reporter