]>
Commit | Line | Data |
---|---|---|
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 | To test a template based component it's frequently necessary to perform the same set of checks for a | |
11 | component instantiated with different template parameters. The __UTF__ provides the ability to create a series of | |
12 | test cases based on a list of desired types and function similar to nullary function template. This facility is | |
13 | called test case template. Here are the two construction interfaces: | |
14 | ||
15 | * Test case template with automated registration | |
16 | * Manually registered test case template | |
17 | ||
18 | [#ref_BOOST_AUTO_TEST_CASE_TEMPLATE][h4 Test case template with automated registration] | |
19 | ||
20 | To create a test case template registered in place of implementation, employ the macro | |
21 | __BOOST_AUTO_TEST_CASE_TEMPLATE__. This facility is also called ['auto test case template]. | |
22 | ||
23 | `` | |
24 | BOOST_AUTO_TEST_CASE_TEMPLATE(test_case_name, formal_type_parameter_name, collection_of_types); | |
25 | `` | |
26 | ||
27 | The macro __BOOST_AUTO_TEST_CASE_TEMPLATE__ requires three arguments: | |
28 | ||
29 | # `test_case_name` The test case template name: unique test cases template identifier | |
30 | # `formal_type_parameter_name` The name of a formal template parameter: | |
31 | name of the type the test case template is instantiated with | |
32 | # The collection of types to instantiate test case template with: arbitrary MPL sequence | |
33 | ||
34 | [bt_example example10..Test case template with automated registration..run-fail] | |
35 | ||
36 | [#ref_BOOST_TEST_CASE_TEMPLATE][h4 Test case template with manual registration] | |
37 | One way to perform the same set of checks for a component instantiated with different template parameters is | |
38 | illustrated in the following example: | |
39 | ||
40 | `` | |
41 | template <typename T> | |
42 | void single_test() | |
43 | { | |
44 | BOOST_CHECK( /* test assertion */ ); | |
45 | } | |
46 | ||
47 | void combined_test() | |
48 | { | |
49 | single_test<int>(); | |
50 | single_test<float>(); | |
51 | single_test<unsigned char>(); | |
52 | } | |
53 | `` | |
54 | ||
55 | ||
56 | There several problems/inconveniences with above approach, including: | |
57 | ||
58 | * Fatal error in one of the invocation will stop whole test case and will skip invocations with different types | |
59 | * You need to repeat function invocation manually for all the parameters you are interested in | |
60 | * You need two functions to implement the test | |
61 | ||
62 | Ideally the test case template would be based on nullary function template (like single_test above). | |
63 | Unfortunately function templates are neither addressable nor can be used as template parameters. To alleviate | |
64 | the issue the manually registered test case template facility consists of two co-working macros: | |
65 | __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ and __BOOST_TEST_CASE_TEMPLATE__. Former is used to define the test case | |
66 | template body, later - to create and register test cases based on it. | |
67 | ||
68 | ||
69 | The macro __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ requires two arguments: | |
70 | ||
71 | # the name of the test case template and | |
72 | # the name of the format type parameter | |
73 | ||
74 | `` | |
75 | BOOST_TEST_CASE_TEMPLATE_FUNCTION(test_case_name, type_name); | |
76 | `` | |
77 | ||
78 | `` | |
79 | BOOST_TEST_CASE_TEMPLATE_FUNCTION( test_case_name, type_name ) | |
80 | { | |
81 | // test case template body | |
82 | } | |
83 | `` | |
84 | ||
85 | The macro __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ is intended to be used in place of nullary function template | |
86 | signature: | |
87 | ||
88 | `` | |
89 | template <typename type_name> | |
90 | void test_case_name() | |
91 | { | |
92 | // test case template body | |
93 | } | |
94 | `` | |
95 | ||
96 | The only difference is that the __BOOST_TEST_CASE_TEMPLATE_FUNCTION__ makes the test case template name usable in | |
97 | the template argument list. | |
98 | ||
99 | ||
100 | __BOOST_TEST_CASE_TEMPLATE__ requires two arguments: | |
101 | ||
102 | # the name of the test case template and | |
103 | # Boost.MPL compatible collection of types to instantiate it with. | |
104 | ||
105 | The names passed to both macros should be the same. | |
106 | ||
107 | ||
108 | `` | |
109 | BOOST_TEST_CASE_TEMPLATE(test_case_name, collection_of_types); | |
110 | `` | |
111 | ||
112 | __BOOST_TEST_CASE_TEMPLATE__ creates an instance of the test case generator. When passed to the method [memberref | |
113 | boost::unit_test::test_suite::add `test_suite::add`], the generator produces a separate sub test case for each type in | |
114 | the supplied collection of types and registers it immediately in the test suite. Each test case is based on the test | |
115 | case template body instantiated with a particular test type. | |
116 | ||
117 | The names for the ['sub test cases] are deduced from the macro argument `test_case_name`. If you prefer to assign | |
118 | different test case names, you need to use the underlying `make_test_case` interface instead. Both test cases creation | |
119 | and registration is performed in the test module initialization function. | |
120 | ||
121 | [tip The test case template facility is preferable to the approach in example above, since execution of each sub test | |
122 | case is guarded and counted separately. It produces a better test log/results report (in example above in case of | |
123 | 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 | |
124 | the sub test case. ] | |
125 | ||
126 | ||
127 | [bt_example example09..Manually registered test case template..run-fail] | |
128 | ||
129 | [endsect] [/template test cases] | |
130 | ||
131 | [/EOF] |