...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The Unit Test Framework supports three different usage variants:
In most cases you shouldn't have problems deciding which one to use, since there are clear reasons why would you prefer each one. Following sections should help you with the decision.
If you prefer to avoid the compilation of standalone library, you should use
the header-only variant of the Unit Test Framework. This
variant only requires you to include the unique header: #include
<boost/test/included/unit_test.hpp>
and
there is no need to link with any library. There are several ways to perform
the initialization, but the simplest way is the following:
#define BOOST_TEST_MODULE
test module name
#include <boost/test/included/unit_test.hpp>
BOOST_TEST_MODULE
macro needs to be
defined before the include and should indicate
the name of the test module. This name can include spaces and does not need
to be wrapped in quotes.
This section gives additional details on how to customize this usage variant. In particular, it is possible to have several compilation units with this variant, as explained in the section Header-only with multiple translation units.
For most users, who has an access to pre-built static library [1] of the Unit Test Framework or can build it themselves, following usage can be most versatile and simple approach. This usage variant entails two steps.
First, the following line needs to be added to all translation units in the test module:
#include <boost/test/unit_test.hpp>
One and only one translation unit should include following lines:
#define BOOST_TEST_MODULE
test module name
#include <boost/test/unit_test.hpp>
BOOST_TEST_MODULE
macro needs
to be defined before the include and should
indicate the name of the test module. This name can include spaces and
does not need to be wrapped in quotes.
![]() |
Note |
---|---|
Header |
The flip side of this usage variant is that each test module following this usage variant is going to be statically linked with Unit Test Framework, which might be something you want to avoid (to save space for example). For more information about these configuration options check this section.
In the project with large number of test modules the static library variant of the Unit Test Framework may cause you to waste a lot of disk space. The solution is to link test module dynamically with the Unit Test Framework built as a shared library. This usage variant entails two steps.
First you need to add following lines to all translation units in a test module:
#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
and only one translation unit should include following lines
#defineBOOST_TEST_MODULE
test module name #defineBOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
BOOST_TEST_MODULE
and
BOOST_TEST_DYN_LINK
macros
needs to be defined before the include.
BOOST_TEST_MODULE
should
be set to test module name. This name can include spaces and does not need
to be wrapped in quotes.
The flip side of this usage variant is that you will need to make sure the Unit Test Framework shared library is accessible at runtime to a test module.
In addition shared library usage variant facilitates custom test runners. For more information about this check this section.
![]() |
Caution |
---|---|
On Windows, the test module and the Unit Test Framework shared library should link to the same CRT. Not doing so (for instance Unit Test Framework shared library in release mode while the test module is in debug) will lead to crashes. |