Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Template test cases

To test a template based component it's frequently necessary to perform the same set of checks for a component instantiated with different template parameters. The Unit Test Framework provides the ability to create a series of test cases based on a list of desired types and function similar to nullary function template. This facility is called test case template. Here are the two construction interfaces:

Test case template with automated registration

To create a test case template registered in place of implementation, employ the macro BOOST_AUTO_TEST_CASE_TEMPLATE. This facility is also called auto test case template.

BOOST_AUTO_TEST_CASE_TEMPLATE(test_case_name, formal_type_parameter_name, collection_of_types);

The macro BOOST_AUTO_TEST_CASE_TEMPLATE requires three arguments:

  1. test_case_name The test case template name: unique test cases template identifier
  2. formal_type_parameter_name The name of a formal template parameter: name of the type the test case template is instantiated with
  3. The collection of types to instantiate test case template with: arbitrary MPL sequence
Example: Test case template with automated registration

Code

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

typedef boost::mpl::list<int,long,unsigned char> test_types;

BOOST_AUTO_TEST_CASE_TEMPLATE( my_test, T, test_types )
{
  BOOST_TEST( sizeof(T) == (unsigned)4 );
}

Output

> example
Running 3 test cases...
test.cpp(17): error: in "my_test<unsigned char>": check sizeof(T) == (unsigned)4 has failed [1 != 4]

*** 1 failure is detected in the test module "example"
Test case template with manual registration

One way to perform the same set of checks for a component instantiated with different template parameters is illustrated in the following example:

template <typename T>
void single_test()
{
  BOOST_CHECK( /* test assertion */ );
}

void combined_test()
{
  single_test<int>();
  single_test<float>();
  single_test<unsigned char>();
}

There several problems/inconveniences with above approach, including:

Ideally the test case template would be based on nullary function template (like single_test above). Unfortunately function templates are neither addressable nor can be used as template parameters. To alleviate the issue the manually registered test case template facility consists of two co-working macros: BOOST_TEST_CASE_TEMPLATE_FUNCTION and BOOST_TEST_CASE_TEMPLATE. Former is used to define the test case template body, later - to create and register test cases based on it.

The macro BOOST_TEST_CASE_TEMPLATE_FUNCTION requires two arguments:

  1. the name of the test case template and
  2. the name of the format type parameter
BOOST_TEST_CASE_TEMPLATE_FUNCTION(test_case_name, type_name);
BOOST_TEST_CASE_TEMPLATE_FUNCTION( test_case_name, type_name )
{
  // test case template body
}

The macro BOOST_TEST_CASE_TEMPLATE_FUNCTION is intended to be used in place of nullary function template signature:

template <typename type_name>
void test_case_name()
{
  // test case template body
}

The only difference is that the BOOST_TEST_CASE_TEMPLATE_FUNCTION makes the test case template name usable in the template argument list.

BOOST_TEST_CASE_TEMPLATE requires two arguments:

  1. the name of the test case template and
  2. Boost.MPL compatible collection of types to instantiate it with.

The names passed to both macros should be the same.

BOOST_TEST_CASE_TEMPLATE(test_case_name, collection_of_types);

BOOST_TEST_CASE_TEMPLATE creates an instance of the test case generator. When passed to the method test_suite::add, the generator produces a separate sub test case for each type in the supplied collection of types and registers it immediately in the test suite. Each test case is based on the test case template body instantiated with a particular test type.

The names for the sub test cases are deduced from the macro argument test_case_name. If you prefer to assign different test case names, you need to use the underlying make_test_case interface instead. Both test cases creation and registration is performed in the test module initialization function.

[Tip] Tip

The test case template facility is preferable to the approach in example above, since execution of each sub test case is guarded and counted separately. It produces a better test log/results report (in example above in case of failure you can't say which type is at fault) and allows you to test all types even if one of them causes termination of the sub test case.

Example: Manually registered test case template

Code

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

BOOST_TEST_CASE_TEMPLATE_FUNCTION( my_test, T )
{
  BOOST_TEST( sizeof(T) == 4U );
}

test_suite* init_unit_test_suite( int /*argc*/, char* /*argv*/[] )
{
  typedef boost::mpl::list<int,long,unsigned char> test_types;

  framework::master_test_suite().
    add( BOOST_TEST_CASE_TEMPLATE( my_test, test_types ) );

  return 0;
}

Output

> example
Running 3 test cases...
test.cpp(15): error: in "my_test<unsigned char>": check sizeof(T) == 4U has failed [1 != 4]

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

PrevUpHomeNext