Boost C++ Libraries

The most common scenario is that you want to write test case without any parameters. The Unit Test Framework provides you with both automatic and manual registration APIs to declare such test case.

Automated registration

To declare a test case without parameters, which is registered in place of implementation, employ the macro BOOST_AUTO_TEST_CASE.

BOOST_AUTO_TEST_CASE(test_case_name);

This API is designed to closely mimic nullary free function declaration syntax. In comparison with free function all you need to do is to skip result type and brackets and wrap test case name into BOOST_AUTO_TEST_CASE:

Example: Nullary function based test case with automated registration

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

BOOST_AUTO_TEST_CASE( free_test_function )
/* Compare with void free_test_function() */
{
  BOOST_TEST( true /* test assertion */ );
}

> example
Running 1 test case...

*** No errors detected

With this macro you don't need to implement any other registration steps. The macro creates and registers the test case with the name free_test_function automatically.

Manual registration

The Unit Test Framework allows to manually create test case without parameters based on nullary free functions, nullary function objects (including those created with boost::bind and nullary boost::function instances). To do this, employ the macro BOOST_TEST_CASE:

BOOST_TEST_CASE(test_function);

BOOST_TEST_CASE creates an instance of the class boost::unit_test::test_case and returns a pointer to the constructed instance. The test case name is deduced from the macro argument test_function. If you prefer to assign a different test case name, you have to use the underlying make_test_case interface instead. To register a new test case, employ the method test_suite::add. Both test case creation and registration are performed in the test module initialization function.

Here is the simplest example of manually registered test case. A single test case is created and registered inside the test module initialization routine. Note that the free function name is passed by address to the macro BOOST_TEST_CASE`.

Example: Nullary free function manually registered

#include <boost/test/included/unit_test.hpp>
using namespace boost::unit_test;

void free_test_function()
{
  BOOST_TEST( true /* test assertion */ );
}

test_suite* init_unit_test_suite( int /*argc*/, char* /*argv*/[] )
{
  framework::master_test_suite().
    add( BOOST_TEST_CASE( &free_test_function ) );

  return 0;
}

> example
Running 1 test case...

*** No errors detected

A test case can be implemented as a method of a class. In this case a pointer to the class instance has to be bound to the test method to create a test case. You can use the same instance of the class for multiple test cases. The Unit Test Framework doesn't take an ownership of the class instance and you are required to manage the class instance lifetime yourself.

	Warning
	The class instance can't be defined in the initialization function scope, since it becomes invalid as soon as the test execution exits it. It needs to be either defined statically/globally or managed using a shared pointer.

Example: Nullary method of a class bound to shared class instance and manually registered

#include <boost/test/included/unit_test.hpp>
#include <boost/bind.hpp>
using namespace boost::unit_test;

class test_class
{
public:
  void test_method1()
  {
    BOOST_TEST( true /* test assertion */ );
  }
  void test_method2()
  {
    BOOST_TEST( false /* test assertion */ );
  }
};

test_suite* init_unit_test_suite( int /*argc*/, char* /*argv*/[] )
{
  boost::shared_ptr<test_class> tester( new test_class );

  framework::master_test_suite().
    add( BOOST_TEST_CASE( boost::bind( &test_class::test_method1, tester )));
  framework::master_test_suite().
    add( BOOST_TEST_CASE( boost::bind( &test_class::test_method2, tester )));
  return 0;
}

> example
Running 2 test cases...
test.cpp(22): error: in "boost::bind( &test_class::test_method2, tester )": check false has failed

*** 1 failure is detected in the test module "Master Test Suite"