C++ Unit Testing Framework: A Boost Test Tutorial

Part 1: Boost Test crash-course

Table of Contents
Part 1: Boost Test crash-course
Part 2: Using Boost Test

So many C++ unit testing framework exist, so why Boost Test Library? The excellent but outdated article Exploring the C++ Unit Testing Framework Jungle showed a nice comparison. Since then, the Boost Test Library evolved a lot. Let's see if it improved.

Comparing the C++ unit test frameworks

After reading the article of Games from Within I tried those promoted and got disappointed by the date of their last release. Finally I checked if the critics against Boost Test where still valid (4 years later).

Unit tests should be minimal to write, and that was Boost Test weakest point in 2004, but Boost 1.36 has auto-test registration without preprocessing making Boost Test one of the best C++ unit testing framework nowadays.

Introducing Boost Test Library

Here is a sample unit test fully running:

// TODO: Include your class to test here.
#include <boost/test/unit_test.hpp>

	// To simplify this example test, let's suppose we'll test 'float'.
	// Some test are stupid, but all should pass.
	float x = 9.5f;

	BOOST_CHECK(x != 0.0f);
	BOOST_CHECK_EQUAL((int)x, 9);
	BOOST_CHECK_CLOSE(x, 9.5f, 0.0001f); // Checks differ no more then 0.0001%

Using auto-registration and fixtures

Usually you'll probably want to have many tests from different files, and fixtures to group the common environment setup and tear-down for a bunch of tests cases. Here's how we could do that to test two classes "CMyFoo" and "CMyBar".

File structure:

  • Runner.cpp: Defines the main() and how to run the tests.
  • MyFooTest.cpp: Unit tests to test CMyFoo.
  • MyBarTest.cpp: Unit tests to test CMyBar.


The runner execute the test cases, its the main(). To customize the output or to run a single test use some command-line arguments. See: Boost.Test > Components > The Unit Test Framework > Components > The Test Log. Example 1: To show more detailed report in XML add command-line arguments: --log_level=all --report_format=XML --report_level=detailed. Example 2: To run all test cases in the suite named "SQLiteDatabaseTest" (with more detailed report), use: --log_level=test_suite --run_test=SQLiteDatabaseTest/*.

#include "StdAfx.h"

#define BOOST_TEST_MODULE "C++ Unit Tests for Foo/Bar"
#include <boost/test/unit_test.hpp>

MyFooTest.cpp (same goes for MyBarTest.cpp)

Here is a fictive example of how to test CMyFoo.

#include "StdAfx.h"
#include "../MyFoo.h"
#include <boost/test/unit_test.hpp>

using namespace std;

struct CMyFooTestFixture
    : m_configFile("test.tmp")
        // TODO: Common set-up each test case here.
        fclose( fopen(m_configFile.c_str(), "w+") );

        // TODO: Common tear-down for each test case here.

    // TODO: Possibly put some common tests.
    void TestSaveLoad(CMyFoo& foo, bool asBinary)

    // TODO: Declare some common values accesses in tests here.
    string m_configFile;


    CMyFoo foo;
    BOOST_REQUIRE(foo.IsValid());   // Stop here if it fails.
    TestSaveLoad(foo, true);
    TestSaveLoad(foo, false);
	BOOST_CHECK_THROW(foo.Save(nullptr), exception);

    CMyFoo foo;
    foo.SetName("  foooooo ");
	BOOST_CHECK_EQUAL(foo.GetName, "  foooooo ");


What's the big deal? To test a new class you simply have to: Create a .cpp file with BOOST_AUTO_TEST_CASE and possibly BOOST_FIXTURE_TEST_SUITE or similar, and that's it!

Next part Using Boost Test

Parts: 1, 2Next