Boost.Test support

Boost.Test is a unit testing framework included in the Boost library.

Adding Boost.Test to your project

You can choose between three usage variants for the framework: header-only, static library, or shared library. When picking the most suitable option, keep in mind that Boost.Test used as header-only might require significant compilation time.

Further on, we will focus on the shared library variant.

Install and build Boost Testing Framework following these instructions.
Note that CLion supports Boost.Test versions 1.55 and later.
Create a folder for Boost tests under the project root. For example, let's call it Boost_tests.
Create a CMakeLists.txt file inside the Boost_tests folder: right-click it in the project tree and select New | CMakeLists.txt.
Customize the following lines and add them into your script:
set (Boost_USE_STATIC_LIBS OFF) find_package (Boost REQUIRED COMPONENTS unit_test_framework) include_directories (${Boost_INCLUDE_DIRS}) # 'Boost_Tests_run' is the target name # 'test1.cpp tests2.cpp' are source files with tests add_executable (Boost_Tests_run test1.cpp tests2.cpp) target_link_libraries (Boost_Tests_run ${Boost_LIBRARIES})
You can also use a live template for boost_with_libs, then adjust the template code to mimic the snippet above.
In your root CMakeLists.txt script, add the add_subdirectory(Boost_tests) command to the end, then reload the project.
In your source files with tests, add the following lines:
#define BOOST_TEST_DYN_LINK #define BOOST_TEST_MAIN // in only one cpp file #include <boost/test/unit_test.hpp>
If you have several .cpp files with tests, #define BOOST_TEST_MAIN should be placed only in one of them.

Live templates for Boost.Test

There are two pre-defined live templates to help you save time on editing CMake scripts with Boost.Test: boost and boost_with_libs. You can find their description and settings in Settings | Editor | Live Templates | CMake.

To insert a template, press Ctrl+J or call Code | Insert Live Template while in CMakeLists.txt. Choose from the list of options, for example:

Or you can start typing the abbreviation and then press Tab to insert the stub code.

Boost.Test run/debug configuration

Although Boost.Test provides the main() entry for your test program, and you can run it as a regular application, we recommend using the dedicated Boost.Test run/debug configuration. It includes test-related settings and let you benefit from the built-in test runner, which is unavailable if you run tests as regular programs.

To create a Boost.Test configuration, go to Run | Edit Configurations, click and select Boost.Test from the list of templates.
Specify the test or suite to be included in the configuration, or provide a pattern for filtering test names. Auto-completion is available in the fields to help you quickly fill them up:
Set wildcards to specify test patterns, for example:
In other fields of the configuration settings, you can set environment variables and command-line arguments.
With Boost.Test version 1.62 or earlier, in case you get the Test framework quit unexpectedly message, set the following string in Program arguments:
--log_format=HRF --log_level=all
Save the configuration, and it's ready for Run or Debug.

Running tests

In CLion, there are several ways to start a run/debug session for tests, one of which is using special gutter icons. These icons help quickly run or debug a single test or a whole suite/fixture:

Gutter icons also show test results (when already available): success or failure .

When you run a test/suite/fixture using gutter icons, CLion creates a temporary Boost.Test configuration, which is greyed out in the configurations list. To save a temporary configuration, select it in the Edit Configurations dialog and press :

Exploring results

When you run tests, CLion shows the results and the process in the built-in test runner window. Test tree shows all the tests while they are being executed one by one. The test runner window includes:

progress bar with the percentage of tests executed so far,
tree view of all the running tests with their status and duration,
tests' output stream,
toolbar with the options to rerun failed tests, export or open previous results saved automatically , sort the tests alphabetically to easily find a particular test, or sort them by duration to understand which test ran longer than others.

Last modified: 11 January 2023