CLion 2021.1 Help

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.

  1. Install and build Boost Testing Framework following these instructions.

    Note that CLion supports Boost.Test versions 1.55 and later.

  2. Create a folder for Boost tests under the project root. For example, let's call it Boost_tests.

  3. 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.

  4. In your root CMakeLists.txt script, add the add_subdirectory(Boost_tests) command to the end, then reload the project.

  5. 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>

    Note that 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 / Preferences | 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:

boost live template

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.

  1. To create a Boost.Test configuration, go to Run | Edit Configurations, click Icons general add and select Boost.Test from the list of templates.

  2. 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:

    completion in configuration fields

    Set wildcards to specify test patterns, for example:

    pattern for tests

  3. 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

  4. Save the configuration, and it's ready for RunIcons actions execute or DebugIcons actions start debugger.

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 for tests

Gutter icons also show test results (when already available): success Icons run configurations test state green2 or failure Icons run configurations test state red2.

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 Icons actions menu saveall:

saving temporary test configuration

Exploring results

When you run tests, CLion shows the results and the process in the built-in test runner window. This 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 Icons run configurations test state red2 tests, export Icons toolbar decorator export or open previous results saved automatically Artwork studio icons profiler toolbar clock, sort the tests alphabetically Icons object browser sorted to easily find a particular test, or sort them by duration Icons run configurations sortby duration to understand which test ran longer than others.

test runner
Last modified: 28 July 2021
Unit testing tutorial Catch2 support