It’s certainly hard to find much fault with the libraries of Boost.  They’re easy to include, they add a terrific amount of power to the STL, and they come with extensive documentation and a thriving community to boost your efforts.  (Awkward pun intended.)  Just about the only library (so far) that I’ve had a hard time finding clear, concise, introductory materials on is Boost.Test.  Boost.Test is a terrific library for facilitating unit testing with your C++ project.  Once you get it setup in your project, Boost.Test makes it very easy to develop and organize unit tests for your project.  But while the Boost.Test documentation will make you a guru with the library, it’s quite a bit lacking in guiding you in getting it going in your project for the very first time.  Googling for direction will lead you (er…led me anyway) down a number of paths which seemed to be overly complex…hopefully this post will help a few people in a similar situation that I was in.

What follows are the fewest steps that I was able to determine for including Boost.Test in your C++ project.  My setup was using CMake 2.8 on Ubuntu 9.04.

1. Download and install Boost following Boost’s online documentation.
2. Create a folder for your tests, e.g., my_project_tests and include a file in it called TestRunner.cpp containing the code below.   When compiled, this “main” class invokes Boost to generate a true main() function for your unit tests and establishes the central testing module.  TestRunner.cpp won’t actually contain any tests, it simply consolidates initialization code that would otherwise be duplicated across your test files and better allows them to be run together.

   #define BOOST_TEST_DYN_LINK
   
   #define BOOST_TEST_MODULE "my_project Unit Tests"
   #include <boost/test/unit_test.hpp>
   

3. Create a file called ExampleTests.cpp in the same folder containing the code below.  This is taken directly from the Boost.Test tutorial with the omission of the test module #define, which was done via TestRunner.cpp.  To add any more tests, you simply create new .cpp files to hold the respective tests and include a reference to the files in your CMakeLists.txt file, as described in the next step.  But first, ExampleTests.cpp:

   #include <boost/test/unit_test.hpp>
   
   int add( int i, int j ) { return i+j; }
   
   BOOST_AUTO_TEST_CASE( my_test )
   {
     // seven ways to detect and report the same error:
     BOOST_CHECK( add( 2,2 ) == 4 );        // #1 continues on error
     BOOST_REQUIRE( add( 2,2 ) == 4 );      // #2 throws on error
   
     if( add( 2,2 ) != 4 )
        BOOST_ERROR( "Ouch..." );            // #3 continues on error
   
     if( add( 2,2 ) != 4 )
       BOOST_FAIL( "Ouch..." );             // #4 throws on error
   
     if( add( 2,2 ) != 4 ) throw "Ouch..."; // #5 throws on error
   
     BOOST_CHECK_MESSAGE( add( 2,2 ) == 4,  // #6 continues on error
       "add(..) result: " << add( 2,2 ) );
     BOOST_CHECK_EQUAL( add( 2,2 ), 4 );      // #7 continues on error
   }

4. In the folder containing TestRunner.cpp, create a CMakeLists.txt containing the code below; this assumes that the CMake version and your project name is defined in a CMakeLists.txt in a parent folder.

   # Include subdirectories for headers
   include_directories(
    "/usr/local/boost_1_42_0"
   )
   
   # Create the unit tests executable
   add_executable(
    my_project_tests
    # Key includes for setting up Boost.Test
    TestRunner.cpp
    # Just for handy reference
    ExampleTests.cpp
   )
   
   # Link the libraries
   target_link_libraries(
    my_project_tests
   
    # "mt" designates that multi-threaded is supported with this Boost library
    boost_unit_test_framework-mt
   )
   

5. Now, simply cmake, make and run the resulting executable to run your unit tests.

Happy testing!

Billy McCafferty