libs/test/doc/test_organization/typed_parametrized_tests.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:test_organization_templates Template test cases]
   9
  10 In order to test a template based component, it is frequently necessary to perform the same set of checks for a
  11 component instantiated with different template parameters.
  12
  13 One way to perform the same set of checks for a component instantiated with different template parameters would be:
  14
  15 ``
  16 template <typename T>
  17 void single_test()
  18 {
  19   BOOST_CHECK( /* test assertion */ );
  20 }
  21
  22 void combined_test()
  23 {
  24   single_test<int>();
  25   single_test<float>();
  26   single_test<unsigned char>();
  27 }
  28 ``
  29
  30 There several problems/inconveniences with above approach, including:
  31
  32 * Fatal error in one of the invocation will stop whole test case and will skip invocations with different types
  33 * You need to repeat function invocation manually for all the parameters you are interested in
  34 * You need two functions to implement the test
  35
  36 The __UTF__ provides a facility, the *template test case*, to create a series of
  37 test cases based on a list of desired types and /nullary/ function. This facility comes with an
  38 [link ref_BOOST_AUTO_TEST_CASE_TEMPLATE automatic] and
  39 [link ref_BOOST_TEST_CASE_TEMPLATE manual] registration interface.
  40
  41 [tip The test case template facility is preferable to the approach in example above, since execution of each sub test
  42 case is guarded and counted separately. It produces a better test log/results report (in example above in case of
  43 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
  44 the sub test case.]
  45
  46 [#ref_BOOST_AUTO_TEST_CASE_TEMPLATE][h4 Template test case with automated registration]
  47
  48 A template test case, registered automatically and in place of its implementation, is declared through the macro
  49 __BOOST_AUTO_TEST_CASE_TEMPLATE__:
  50
  51 ``
  52 BOOST_AUTO_TEST_CASE_TEMPLATE(test_case_name, formal_type_parameter_name, collection_of_types);
  53 ``
  54
  55 The arguments are as follow:
  56
  57 # `test_case_name`: the test case template name: unique test cases template identifier
  58 # `formal_type_parameter_name`: the name of a formal template parameter:
  59          name of the type the test case template is instantiated with
  60 # `collection_of_types`: the collection of types to instantiate test case template with.
  61   This is an *arbitrary MPL sequence* or a sequence of types wrapped in a `std::tuple`
  62   (since [link ref_CHANGE_LOG_3_7 __UTF__ v3.7], if supported by the compiler)
  63
  64 The resulting name of the test is a composition of the `test_case_name` parameter and the current
  65 type being tested. Since [link ref_CHANGE_LOG_3_12 __UTF__ v3.12], the framework tries to unify
  66 the name of the resulting type across various platforms such that they are easier to reference
  67 from the [link boost_test.runtime_config.test_unit_filtering command line filter].
  68
  69 [bt_example example10..Test case template with automated registration..run-fail]
  70
  71 [warning Since [link ref_CHANGE_LOG_3_7 __UTF__ v3.7], the __UTF__ does not allow for duplicate test case name
  72  under the same test suite. As test names are derived from the types in the `collection_of_types`,
  73  this indirectly means that *having a duplicate type* in the
  74  `collection_of_types` *yields an error*.]
  75
  76 [note If you prefer having the template parameter list directly in the declaration of __BOOST_AUTO_TEST_CASE_TEMPLATE__,
  77   you may use the macro [@www.boost.org/doc/libs/release/libs/utility/identity_type/doc/html/index.html `BOOST_IDENTITY_TYPE`].
  78   The previous example gives (note the double parenthesis around the MPL list):
  79
  80   ``
  81   #include <boost/utility/identity_type.hpp>
  82
  83   BOOST_AUTO_TEST_CASE_TEMPLATE(
  84     my_test,
  85     T,
  86     BOOST_IDENTITY_TYPE((boost::mpl::list<
  87       int,
  88       long,
  89       unsigned char
  90     >)) )
  91   {
  92     BOOST_TEST( sizeof(T) == (unsigned)4 );
  93   }
  94   ``
  95 ]
  96
  97 [#ref_BOOST_TEST_CASE_TEMPLATE][h4 Test case template with manual registration]
  98 To manually register template test cases, two macros should be used:
  99
 100 * __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ to define the template test case body
 101 * __BOOST_TEST_CASE_TEMPLATE__ to register the test case based on the previous declaration
 102
 103 The macro __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ requires two arguments:
 104
 105 # the name of the test case template and
 106 # the name of the format type parameter
 107
 108 ``
 109   BOOST_TEST_CASE_TEMPLATE_FUNCTION(test_case_name, type_name);
 110 ``
 111
 112 ``
 113 BOOST_TEST_CASE_TEMPLATE_FUNCTION( test_case_name, type_name )
 114 {
 115   // test case template body
 116 }
 117 ``
 118
 119 The macro __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ is intended to be used in place of nullary function template
 120 signature:
 121
 122 ``
 123 template <typename type_name>
 124 void test_case_name()
 125 {
 126   // test case template body
 127 }
 128 ``
 129
 130 The only difference is that the __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ makes the test case template name usable in
 131 the template argument list.
 132
 133 __BOOST_TEST_CASE_TEMPLATE__ requires two arguments:
 134
 135 # the name of the test case template and
 136 # Boost.MPL compatible collection of types to instantiate it with.
 137
 138 The names passed to both macros should be the same.
 139
 140 ``
 141   BOOST_TEST_CASE_TEMPLATE(test_case_name, collection_of_types);
 142 ``
 143
 144 [bt_example example09..Manually registered test case template..run-fail]
 145
 146 __BOOST_TEST_CASE_TEMPLATE__ creates an instance of the test case generator. When passed to the method [memberref
 147 boost::unit_test::test_suite::add `test_suite::add`], the generator produces a separate sub test case for each type in
 148 the supplied collection of types and registers it immediately in the test suite. Each test case is based on the test
 149 case template body instantiated with a particular test type.
 150
 151 The names for the ['sub test cases] are deduced from the macro argument `test_case_name`. If you prefer to assign
 152 different test case names, you need to use the underlying [headerref boost/test/tree/test_unit.hpp `make_test_case`] interface instead.
 153 Both test cases creation and registration is performed in the test module initialization function.
 154
 155 [warning Since [link ref_CHANGE_LOG_3_7 __UTF__ v3.7], the __UTF__ does not allow for duplicate test case name
 156  under the same test suite. As test names are derived from the types in the `collection_of_types`,
 157  this indirectly means that having a duplicate of types in the
 158  `collection_of_types` will yield an error.]
 159
 160 [endsect] [/template test cases]
 161
 162 [/EOF]