]>
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:param_test Parametrized test cases] | |
9 | ||
10 | [caution the functionalities presented on this page have been superseded by the | |
11 | [link boost_test.tests_organization.test_cases.test_case_generation Data-driven test case] facility.] | |
12 | ||
13 | ||
14 | Some tests are required to be repeated for a series of different input parameters. One way to achieve this is | |
15 | manually register a test case for each parameter as in the previous examples. You can also invoke a test function with | |
16 | all parameters manually from within your test case, like this: | |
17 | ||
18 | `` | |
19 | void single_test( int i ) | |
20 | { | |
21 | BOOST_CHECK( /* test assertion */ ); | |
22 | } | |
23 | ||
24 | void combined_test() | |
25 | { | |
26 | int params[] = { 1, 2, 3, 4, 5 }; | |
27 | std::for_each( params, params+5, &single_test ); | |
28 | } | |
29 | `` | |
30 | ||
31 | The __UTF__ presents a better solution for this problem: the unary function based test case, also referred as | |
32 | ['parametrized test case]. The unary test function can be a free function, unary functor (for example created | |
33 | with `boost::bind`) or unary method of a class with bound test class instance). The test function is converted | |
34 | into test case using the macro `BOOST_PARAM_TEST_CASE`. The macro expects a collection of parameters (passed as | |
35 | two input iterators) and an unary test function: | |
36 | ||
37 | `` | |
38 | BOOST_PARAM_TEST_CASE(test_function, params_begin, params_end); | |
39 | `` | |
40 | ||
41 | ||
42 | `BOOST_PARAM_TEST_CASE` creates an instance of the test case generator. When passed to the method | |
43 | [memberref boost::unit_test::test_suite::add `test_suite::add`], the generator produces a separate sub test case | |
44 | for each parameter in the parameters collection and registers it immediately in a test suite. | |
45 | Each test case is based on a test function with the parameter bound by value, | |
46 | even if the test function expects a parameter by reference. The fact that parameter value is stored along with | |
47 | bound test function releases you from necessity to manage parameters lifetime. For example, they can be defined | |
48 | in the test module initialization function scope. | |
49 | ||
50 | All sub test case names are deduced from the macro argument `test_function`. If you prefer to assign different | |
51 | names, you have to use the underlying [headerref boost/test/parameterized_test.hpp `make_test_case`] interface instead. Both test cases creation and | |
52 | registration are performed in the test module initialization function. | |
53 | ||
54 | The parametrized test case facility is preferable to the approach in the example above, since execution of | |
55 | each sub test case is guarded and counted independently. It produces a better test log/results report (in | |
56 | example above in case of failure you can't say which parameter is at fault) and allows you to test against | |
57 | all parameters even if one of them causes termination a particular sub test case. | |
58 | ||
59 | In comparison with a manual test case registration for each parameter approach the parametrized test case | |
60 | facility is more concise and easily extensible. | |
61 | ||
62 | In following simple example the same test, implemented in `free_test_function`, is | |
63 | performed for 5 different parameters. The parameters are defined in the test module initialization function | |
64 | scope. The master test suite contains 5 independent test cases. | |
65 | ||
66 | [bt_example example07..Unary free function based test case..run-fail] | |
67 | ||
68 | Next example is similar, but instead of a free function it uses a method of a class. Even though parameters are | |
69 | passed into test method by reference you can still define them in the test module initialization function scope. | |
70 | This example employs the alternative test module initialization function specification. | |
71 | ||
72 | [bt_example example08..Unary class method based test case..run-fail] | |
73 | ||
74 | [endsect] [/test case with arity] | |
75 | ||
76 | [/EOF] |