Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Frequently Asked Questions

Where the latest version of the Boost Test Library is located?

The latest version of Boost Test Library is available online at http://www.boost.org/libs/test.

Bug report of feature request: what should I do?

You can send a bug report or a feature request to the boost users' mailing list boost-users@lists.boost.org and/or fill a ticket on the GitHub issues of the project https://github.com/boostorg/test.

How to create test case using the Unit Test Framework?

To create a test case, use the macro

BOOST_AUTO_TEST_CASE( test_function );

For more details see the Unit Test Framework BOOST_AUTO_TEST_CASE documentation.

Is Boost.Test thread safe?

Short answer: no, but we welcome patches!

Longer answer: Boost.Test currently has no synchronization mechanisms in place to avoid any race when multiple threads are calling the assertion macros. For instance this code

BOOST_TEST_CASE(test_parallel)
{
    std::vector<std::string> vect(10);
    std::for_each(
        std::execution::par_unseq,
        vect.begin(),
        vect.end(),
        [](auto const& str)
        {
            BOOST_TEST(str == "");
        });
}

will not work as expected as the assertion BOOST_TEST will be called from multiple threads.

How to create test suite using the Unit Test Framework?

To create a test suite use the macro

BOOST_AUTO_TEST_SUITE( suite_name );

For more details see the Unit Test Framework BOOST_AUTO_TEST_SUITE documentation.

Why did I get a linker error when compiling my test program?

Boost Test Library components provide several usage variants: to create a test program you can link with the one of the precompiled library variants or use header-only variant. For example, to use Unit Test Framework you may either include

#include <boost/test/unit_test.hpp>

and link with

libunit_test_framework.lib

or you can include

#include <boost/test/included/unit_test.hpp>

in which case you should not need to link with any pre-compiled component. Note also that you should strictly follow specification on initialization function in other case some compilers may produce linker error like this.

Unresolved external init_unit_test_suite(int, char**).

The reason for this error is that in your implementation you should specify second argument of init_unit_test_suite exactly as in the specification, i.e.: char* [].

How can I redirect testing output?

Use

unit_test_log::instance().set_log_output( std::ostream & )

For more details see the Unit Test Framework output test stream documentation.

I want different default log trace level

Use environment variable BOOST_TEST_LOG_LEVEL to define desired log trace level. You still will be able to reset this value from the command line. For the list of acceptable values see the Unit Test Framework runtime configuration documentation.

Is there DLL version of Boost.Test components available on Win32 platform?

Yes. Starting with Boost 1.34.0.

How to set up a CMake project using Unit Test Framework (extended)

Suppose, you are building a test module from one translation unit test_file.cpp. First, let's do it using the header-only usage variant of the Unit Test Framework.

Let's paste the following content in a CMakeLists.txt at the same location than our test file test_file.cpp:

cmake_minimum_required(VERSION 2.8.7)
project(my_first_test)
enable_testing()

# indicates the location of the boost installation tree.
# hard-coded for our simple example.
set(BOOST_INCLUDE_DIRS $boost_installation_prefix/include)

# creates the executable
add_executable(test_executable test_file.cpp)
# indicates the include paths
target_include_directories(test_executable PRIVATE ${BOOST_INCLUDE_DIRS})

# declares a test with our executable
add_test(NAME test1 COMMAND test_executable)

We will now create the build directory for this project (separate directory), configure and build the project, as follow:

> cd $test_path
> mkdir build     1
> cd build
> cmake  ..       2
> cmake --build . 3
> ctest           4

1

we create a directory dedicated to the build, to avoid any pollution of the sources with the temporary build files

2

configuration of the project

3

this command builds the project, cmake drives a native tool that is configured on the previous command line

4

runs the tests declared in the project and prints a report

In the case you are using the shared libraries variant of Unit Test Framework, some modifications should be done in your CMakeLists.txt.

cmake_minimum_required(VERSION 2.8.11)
project(my_first_test)
enable_testing()

# replace XX with the version you have
set(Boost_ADDITIONAL_VERSIONS "1.XX" "1.XX.0")

# finds boost, triggers an error otherwise
find_package(Boost XX REQUIRED COMPONENTS unit_test_framework)

# creates the executable
add_executable(test_executable test_file.cpp)
# indicates the include paths
target_include_directories(test_executable PRIVATE ${Boost_INCLUDE_DIRS})
# indicates the shared library variant
target_compile_definitions(test_executable PRIVATE "BOOST_TEST_DYN_LINK=1")
# indicates the link paths
target_link_libraries(test_executable ${Boost_UNIT_TEST_FRAMEWORK_LIBRARY})

# declares a test with our executable
add_test(NAME test1 COMMAND test_executable)

We will now create the build directory for this project (separate directory), configure and build the project, as follow:

> cd $test_path
> mkdir build 1
> cd build
> cmake -DBOOST_ROOT=$boost_installation_prefix .. 2
> cmake --build . 3
> ctest           4

1

we create a directory dedicated to the build, to avoid any pollution of the sources with the temporary build files

2

configuration of the project, the BOOST_ROOT configuration element indicates the Boost module of cmake where to find our installation

3

this command builds the project, cmake drives a native tool that is configured on the previous command line

4

runs the tests declared in the project and prints a report


PrevUpHomeNext