Boost.Test

Boost.Test basics

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

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()

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

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>
```
note
If you have several .cpp files with tests, #define BOOST_TEST_MAIN should be placed only in one of them.

tip
See Quick CMake Tutorial and the example given in Unit Testing Tutorial

Live templates for Boost.Test

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 in the main menu, 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.

note
Instead of editing a single configuration, you can modify the Boost.Test template itself. In this case, the settings you specify will apply as defaults to all new configurations of this type.

See also

Procedures

Getting Started

Boost.Test﻿

Boost.Test basics﻿

Checkers﻿

Suites﻿

Fixtures﻿

Adding Boost.Test to your project﻿

note

tip

Live templates for Boost.Test﻿

Boost.Test run/debug configuration﻿

note

Running tests﻿

Exploring results﻿

tip

See also

Procedures

Getting Started

Boost.Test

Boost.Test basics

Checkers

Suites

Fixtures

Adding Boost.Test to your project

Live templates for Boost.Test

Boost.Test run/debug configuration

Running tests

Exploring results