bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / test / doc / test_organization / typed_parametrized_tests.qbk

[/
 / Copyright (c) 2003 Boost.Test contributors 
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]
 
[section:test_organization_templates 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 __UTF__ 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
* Manually registered test case template

[#ref_BOOST_AUTO_TEST_CASE_TEMPLATE][h4 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:

# `test_case_name` The test case template name: unique test cases template identifier
# `formal_type_parameter_name` The name of a formal template parameter:
         name of the type the test case template is instantiated with
# The collection of types to instantiate test case template with: arbitrary MPL sequence

[bt_example example10..Test case template with automated registration..run-fail]

[#ref_BOOST_TEST_CASE_TEMPLATE][h4 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:

* Fatal error in one of the invocation will stop whole test case and will skip invocations with different types
* You need to repeat function invocation manually for all the parameters you are interested in
* You need two functions to implement the test

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: 

# the name of the test case template and 
# 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: 

# the name of the test case template and 
# 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 [memberref
boost::unit_test::test_suite::add `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 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. ]


[bt_example example09..Manually registered test case template..run-fail]

[endsect] [/template test cases]

[/EOF]