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_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
    # Create the unit tests executable
     # Key includes for setting up Boost.Test
     # Just for handy reference
    # Link the libraries
     # "mt" designates that multi-threaded is supported with this Boost library
  5. Now, simply cmake, make and run the resulting executable to run your unit tests.

Happy testing!

Billy McCafferty