# Boost.Test

[Boost unit testing framework
(Boost.Test)](https://www.boost.org/doc/libs/1_71_0/libs/test/doc/html/index.html) is a part of the [Boost](https://www.boost.org/) library. It is a fully functional and scalable framework, with a 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](https://github.com/google/googlemock).

## 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:

```CPLUSPLUS
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:       ```CPLUSPLUS 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](https://www.boost.org/doc/libs/1_71_0/libs/test/doc/html/boost_test/tests_organization/test_tree/test_suite.html) using the pair of `BOOST_AUTO_TEST_SUITE(suite_name)` and `BOOST_AUTO_TEST_SUITE_END()` macros. A simple test suite looks like this:

```CPLUSPLUS
#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](https://www.boost.org/doc/libs/1_71_0/libs/test/doc/html/boost_test/tests_organization/fixtures.html) written after a fixture class declaration or a special `BOOST_FIXTURE_TEST_CASE` macro:

```CPLUSPLUS
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](https://www.boost.org/doc/libs/1_70_0/libs/test/doc/html/boost_test/usage_variants.html) 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](https://www.boost.org/doc/libs/1_70_0/libs/test/doc/html/boost_test/usage_variants.html#boost_test.usage_variants.shared_lib).

Procedure:

1. Install and build Boost Testing Framework following these [instructions](https://www.boost.org/doc/libs/1_70_0/libs/test/doc/html/boost_test/adv_scenarios/build_utf.html).

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:

```CMAKE
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](#live-templates-boost) 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:

```CPLUSPLUS
#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](https://resources.jetbrains.com/stardust/clion/2019.2/quick-cmake-tutorial.html#boost) and the [example](unit-testing-tutorial.html#adding-framework) given in Unit Testing Tutorial

## Live templates for Boost.Test

There are two pre-defined [live templates](using-live-templates.html) 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` (Windows), `⌘ J` (macOS), `⌘ J` (IntelliJ IDEA Classic (macOS)), `⌘ J` (macOS System Shortcuts), `Ctrl+J` (XWin), `Ctrl+J` (GNOME), `Ctrl+J` (KDE), `Ctrl+J` (Emacs), `Ctrl+J` (Sublime Text), `Ctrl+J` (Sublime Text (macOS)), `⌘ J` (Xcode), `Ctrl+K, X` (Visual Studio), `⌘ E, L` (Visual Studio (macOS)), `Ctrl+J` (ReSharper), `⌘ J` (ReSharper (macOS)), `Ctrl+J` (QtCreator), `Ctrl+J` (QtCreator (macOS)), `Ctrl+J` (NetBeans), `Ctrl+Alt+Shift+J` (Eclipse), `Ctrl+J` (Eclipse (macOS)) or call `Code | Insert Live Template` while in `CMakeLists.txt`. Choose from the list of options, for example:

![Boost live template](https://resources.jetbrains.com/help/img/idea/2026.2/cl_cmake_boosttemplate.png)

Or you can start typing the abbreviation and then press `Tab` (Windows), `⇥` (macOS), `⇥` (IntelliJ IDEA Classic (macOS)), `⇥` (macOS System Shortcuts), `Tab` (XWin), `Tab` (GNOME), `Tab` (KDE), `Tab` (Emacs), `Tab` (Sublime Text), `⇥` (Sublime Text (macOS)), `⇥` (Xcode), `Tab` (Visual Studio), `⇥` (Visual Studio (macOS)), `Tab` (ReSharper), `⇥` (ReSharper (macOS)), `Tab` (QtCreator), `⇥` (QtCreator (macOS)), `Tab` (NetBeans), `Tab` (Eclipse), `⇥` (Eclipse (macOS)) 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](#test-runner), which is unavailable if you run tests as regular programs.

Procedure:

1. To create a Boost.Test configuration, go to Run | Edit Configurations in the main menu, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) 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](https://resources.jetbrains.com/help/img/idea/2026.2/cl_boosttest_config_completion.png)

Set wildcards to specify test patterns, for example:

![pattern for tests](https://resources.jetbrains.com/help/img/idea/2026.2/cl_googletest_config_pattern.png)

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 :

```SHELL
--log_format=HRF --log_level=all
```

4. Save the configuration, and it's ready for Run ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) or Debug ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.startDebugger.svg) .

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

## Running tests

In CLion, there are [several ways](performing-tests.html) 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](https://resources.jetbrains.com/help/img/idea/2026.2/cl_boosttest_guttericons.png)

Gutter icons also show test results (when already available): success ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.green2.svg) or failure ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.red2.svg) .

When you run a test/suite/fixture using gutter icons, CLion creates a [temporary](run-debug-configuration.html) 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 ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.save.svg):

![Saving temporary test configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_boosttest_tempconfig.png)

## Exploring results

When you run tests, CLion shows the results and the process in the built-in [test runner window](viewing-and-exploring-test-results.html). 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 ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.testState.red2.svg) tests, export ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.export.svg) or open previous results saved automatically ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.vcs.history.svg) , sort the tests alphabetically ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.objectBrowser.sorted.svg) to easily find a particular test, or sort them by duration ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.runConfigurations.sortbyDuration.svg) to understand which test ran longer than others.

> **Tip:**
> CLion test runner also supports Boost.Test [decorators](https://www.boost.org/doc/libs/1_60_0/libs/test/doc/html/boost_test/tests_organization/decorators.html), such as `boost::unit_test::disabled()/enabled()`.

![test runner](https://resources.jetbrains.com/help/img/idea/2026.2/cl_boosttest_runner.png)

## See also

### Getting Started

[Unit testing tutorial](unit-testing-tutorial.html) [Quick CMake tutorial](quick-cmake-tutorial.html)

### Procedures

[Run/Debug/Terminate Tests](performing-tests.html) [Explore Test Results](viewing-and-exploring-test-results.html)