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