How to Run the Unit Tests

Unit tests are an essential part of maintaining a reliable and stable codebase. This project uses the Erbsland Unit Test framework, which provides a clean and expressive syntax for writing and organizing tests.

Follow the steps below to compile and run the tests locally.

Compile the Unit Tests

To build the unit tests in debug mode using CMake and Ninja:

$ cmake -S . -B cmake-build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
$ cmake --build cmake-build-debug --config Debug

Alternatively, you can create your build directory outside the repository. In that case, adjust the paths accordingly in the following commands:

$ mkdir ~/build
$ cd ~/build
$ cmake -S /path/to/src/erbsland-cpp-configuration -G Ninja -DCMAKE_BUILD_TYPE=Debug
$ cmake --build . --config Debug

The option -G Ninja selects the Ninja build system, which we recommend for its speed and efficiency. You can omit this option to fall back to the default generator available on your system.

Run All Unit Tests

After compiling, you can execute all unit tests with the following commands:

$ cd cmake-build-debug
$ ctest .

This tells CTest to run all tests defined in the current build directory. Be sure you’re inside the right directory—otherwise, it won’t find the tests.

Run Individual Tests

During development, it’s often more efficient to run only a specific test suite. You can do this directly via the test binary:

$ ./cmake-build-debug/test/unittest/unittest name:Date

In this example, only the Date test suite (implemented in the DateTest class) is executed.

To explore all available test suites, targets, and tags, run:

$ ./cmake-build-debug/test/unittest/unittest --list

Filter Syntax

You can filter which tests to run using the format [+|-]<type>:<name>. This makes it easy to include or exclude specific tests:

  • name:TestX — runs only the specified test or suite

  • +tag:Slow — explicitly includes tests tagged Slow, even if they’re skipped by default

  • -name:DateTest — runs all tests except DateTest

Available Types

  • name: Name of a test class or individual test method

  • tag: A custom tag you’ve assigned to tests

  • target: A logical target or component under test

Options for Automation

These options are especially useful in CI environments or automated scripts:

  • -c, --no-color — disables colorized terminal output

  • -e — stops test execution after the first error

  • -s, --no-summary — skips the end-of-run summary output

More Information

You’ll find comprehensive documentation in the local path: test/unittest/erbsland-unittest/doc Or check the online docs at: Erbsland Unit Test Documentation

For a quick overview of all supported options, simply run:

./cmake-build-debug/test/unittest/unittest --help