Boost.Test

Boost unit testing framework (Boost.Test) is a part of the Boost library. It is a fully-functional and scalable framework, with wide range of assertion macros, XML output, and other features. Boost.Test itself lacks mocking functionality, but it can be combined with stand-alone mocking frameworks such as gmock.

Boost.Test basics

If you are not familiar with Boost.Test, you can find a description of its main concepts below:

Checkers

For most of the Boost.Test checkers, you can set a severity level:

WARN produces a warning message if the check failed, but the error counter isn't increased and the test case continues.
CHECK reports an error and increases the error counter when the check is failed, but the test case continues.
REQUIRE is used for reporting fatal errors, when the execution of the test case should be aborted (for example, to check whether an object that will be used later was created successfully).

This way, a Boost checker is usually a macro of the BOOST_[level]_[checkname] format that takes one or several arguments. Basic macros are BOOST_WARN, BOOST_CHECK, and BOOST_REQUIRE. They take one argument of an expression to check, for example:

BOOST_WARN(sizeof(int) == sizeof(long));
BOOST_CHECK( i == 1 );
BOOST_REQUIRE( j > 5 );

A few examples of other checkers are given below:


General comparison	`BOOST_[level]_EQUAL`, `BOOST_[level]_NE`, `BOOST_[level]_GT` In case of failure, these macros not only give the test failed message, but also show the expected and the actual value: int i = 2; int j = 1; BOOST_CHECK( i == j ); // reports the fact of failure only: "check i == j failed" BOOST_CHECK_EQUAL( i, j ); // reports "check i == j failed [2 != 1]"
Float point comparison	`BOOST_[level]_CLOSE` / `BOOST_[level]_CLOSE_FRACTION` / `BOOST_[level]_SMALL`
Exception checking	`BOOST_[level]_THROW` / `BOOST_[level]_NO_THROW` / `BOOST_[level]_EXCEPTION`

General comparison

BOOST_[level]_EQUAL, BOOST_[level]_NE, BOOST_[level]_GT

In case of failure, these macros not only give the test failed message, but also show the expected and the actual value:

int i = 2;
int j = 1;
BOOST_CHECK( i == j );     // reports the fact of failure only: "check i == j failed"
BOOST_CHECK_EQUAL( i, j ); // reports "check i == j failed [2 != 1]"

Float point comparison

BOOST_[level]_CLOSE / BOOST_[level]_CLOSE_FRACTION / BOOST_[level]_SMALL

Exception checking

BOOST_[level]_THROW / BOOST_[level]_NO_THROW / BOOST_[level]_EXCEPTION

Suites

You can organize Boost tests into suites using the pair of BOOST_AUTO_TEST_SUITE(suite_name) and BOOST_AUTO_TEST_SUITE_END() macros. A simple test suite looks like this:

#define BOOST_TEST_MODULE Suite_example
#include <boost/test/unit_test.hpp>

BOOST_AUTO_TEST_SUITE(TwoTwoFour_suite)
BOOST_AUTO_TEST_CASE(testPlus) {
BOOST_CHECK_EQUAL(2+2, 4);
}
BOOST_AUTO_TEST_CASE(testMult) {
BOOST_CHECK_EQUAL(2*2, 4);
}
BOOST_AUTO_TEST_SUITE_END()

Fixtures

To write a fixture with Boost, you can use either a regular BOOST_AUTO_TEST_CASE macro written after a fixture class declaration or a special BOOST_FIXTURE_TEST_CASE macro:

struct SampleF {
SampleF() : i(1) { }
~SampleF() { }
int i;
};

BOOST_FIXTURE_TEST_CASE(SampleF_test, SampleF) {
// accessing i from SampleF directly
BOOST_CHECK_EQUAL(i, 1);
BOOST_CHECK_EQUAL(i, 2);
BOOST_CHECK_EQUAL(i, 3);
}

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 test2.cpp' are source files with tests add_executable (Boost_Tests_run test1.cpp test2.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 Control+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 list of configurations. 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: 13 November 2023