1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Parametrized test cases</title> 5<link rel="stylesheet" href="../../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../../index.html" title="Boost.Test"> 8<link rel="up" href="../test_cases.html" title="Test cases"> 9<link rel="prev" href="test_organization_templates.html" title="Template test cases"> 10<link rel="next" href="../test_tree.html" title="Test tree"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="test_organization_templates.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_cases.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../test_tree.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_test.tests_organization.test_cases.param_test"></a><a class="link" href="param_test.html" title="Parametrized test cases">Parametrized 28 test cases</a> 29</h4></div></div></div> 30<div class="caution"><table border="0" summary="Caution"> 31<tr> 32<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td> 33<th align="left">Caution</th> 34</tr> 35<tr><td align="left" valign="top"><p> 36 the functionalities presented on this page have been superseded by the 37 <a class="link" href="test_case_generation.html" title="Data-driven test cases">Data-driven 38 test case</a> facility. 39 </p></td></tr> 40</table></div> 41<p> 42 Some tests are required to be repeated for a series of different input 43 parameters. One way to achieve this is manually register a test case for 44 each parameter as in the previous examples. You can also invoke a test 45 function with all parameters manually from within your test case, like 46 this: 47 </p> 48<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">single_test</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">)</span> 49<span class="special">{</span> 50 <span class="identifier">BOOST_CHECK</span><span class="special">(</span> <span class="comment">/* test assertion */</span> <span class="special">);</span> 51<span class="special">}</span> 52 53<span class="keyword">void</span> <span class="identifier">combined_test</span><span class="special">()</span> 54<span class="special">{</span> 55 <span class="keyword">int</span> <span class="identifier">params</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">5</span> <span class="special">};</span> 56 <span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">(</span> <span class="identifier">params</span><span class="special">,</span> <span class="identifier">params</span><span class="special">+</span><span class="number">5</span><span class="special">,</span> <span class="special">&</span><span class="identifier">single_test</span> <span class="special">);</span> 57<span class="special">}</span> 58</pre> 59<p> 60 The <span class="emphasis"><em>Unit Test Framework</em></span> presents a better solution 61 for this problem: the unary function based test case, also referred as 62 <span class="emphasis"><em>parametrized test case</em></span>. The unary test function can 63 be a free function, unary functor (for example created with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>) or unary method of a class with 64 bound test class instance). The test function is converted into test case 65 using the macro <code class="computeroutput"><span class="identifier">BOOST_PARAM_TEST_CASE</span></code>. 66 The macro expects a collection of parameters (passed as two input iterators) 67 and an unary test function: 68 </p> 69<pre class="programlisting"><span class="identifier">BOOST_PARAM_TEST_CASE</span><span class="special">(</span><span class="identifier">test_function</span><span class="special">,</span> <span class="identifier">params_begin</span><span class="special">,</span> <span class="identifier">params_end</span><span class="special">);</span> 70</pre> 71<p> 72 <code class="computeroutput"><span class="identifier">BOOST_PARAM_TEST_CASE</span></code> creates 73 an instance of the test case generator. When passed to the method <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html#idm45267286747104-bb">test_suite::add</a></code>, 74 the generator produces a separate sub test case for each parameter in the 75 parameters collection and registers it immediately in a test suite. Each 76 test case is based on a test function with the parameter bound by value, 77 even if the test function expects a parameter by reference. The fact that 78 parameter value is stored along with bound test function releases you from 79 necessity to manage parameters lifetime. For example, they can be defined 80 in the test module initialization function scope. 81 </p> 82<p> 83 All sub test case names are deduced from the macro argument <code class="computeroutput"><span class="identifier">test_function</span></code>. If you prefer to assign 84 different names, you have to use the underlying <code class="computeroutput"><a class="link" href="../../../header/boost/test/parameterized_test_hpp.html" title="Header <boost/test/parameterized_test.hpp>">make_test_case</a></code> interface 85 instead. Both test cases creation and registration are performed in the 86 test module initialization function. 87 </p> 88<p> 89 The parametrized test case facility is preferable to the approach in the 90 example above, since execution of each sub test case is guarded and counted 91 independently. It produces a better test log/results report (in example 92 above in case of failure you can't say which parameter is at fault) and 93 allows you to test against all parameters even if one of them causes termination 94 a particular sub test case. 95 </p> 96<p> 97 In comparison with a manual test case registration for each parameter approach 98 the parametrized test case facility is more concise and easily extensible. 99 </p> 100<p> 101 In following simple example the same test, implemented in <code class="computeroutput"><span class="identifier">free_test_function</span></code>, is performed for 102 5 different parameters. The parameters are defined in the test module initialization 103 function scope. The master test suite contains 5 independent test cases. 104 </p> 105<h6> 106<a name="boost_test.tests_organization.test_cases.param_test.h0"></a> 107 <span class="phrase"><a name="boost_test.tests_organization.test_cases.param_test.example_descr"></a></span><a class="link" href="param_test.html#boost_test.tests_organization.test_cases.param_test.example_descr">Example: 108 Unary free function based test case</a> 109 </h6> 110<div class="informaltable"><table class="table"> 111<colgroup><col></colgroup> 112<thead><tr><th> 113 <p> 114 Code 115 </p> 116 </th></tr></thead> 117<tbody><tr><td> 118<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 119<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">parameterized_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 120<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span> 121 122<span class="keyword">void</span> <span class="identifier">free_test_function</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">)</span> 123<span class="special">{</span> 124 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">4</span> <span class="comment">/* test assertion */</span> <span class="special">);</span> 125<span class="special">}</span> 126 127<span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span> 128<span class="special">{</span> 129 <span class="keyword">int</span> <span class="identifier">params</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">,</span> <span class="number">5</span> <span class="special">};</span> 130 131 <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span> 132 <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_PARAM_TEST_CASE</span><span class="special">(</span> <span class="special">&</span><span class="identifier">free_test_function</span><span class="special">,</span> <span class="identifier">params</span><span class="special">,</span> <span class="identifier">params</span><span class="special">+</span><span class="number">5</span> <span class="special">)</span> <span class="special">);</span> 133 134 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 135<span class="special">}</span> 136</pre> 137 </td></tr></tbody> 138</table></div> 139<div class="informaltable"><table class="table"> 140<colgroup><col></colgroup> 141<thead><tr><th> 142 <p> 143 Output 144 </p> 145 </th></tr></thead> 146<tbody><tr><td> 147<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> 148<span class="identifier">Running</span> <span class="number">5</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span> 149<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"free_test_function"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">4</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">4</span> <span class="special">>=</span> <span class="number">4</span><span class="special">]</span> 150<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"free_test_function"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special"><</span> <span class="number">4</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">5</span> <span class="special">>=</span> <span class="number">4</span><span class="special">]</span> 151 152<span class="special">***</span> <span class="number">2</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span> 153</pre> 154 </td></tr></tbody> 155</table></div> 156<p> 157 Next example is similar, but instead of a free function it uses a method 158 of a class. Even though parameters are passed into test method by reference 159 you can still define them in the test module initialization function scope. 160 This example employs the alternative test module initialization function 161 specification. 162 </p> 163<h6> 164<a name="boost_test.tests_organization.test_cases.param_test.h1"></a> 165 <span class="phrase"><a name="boost_test.tests_organization.test_cases.param_test.example_descr0"></a></span><a class="link" href="param_test.html#boost_test.tests_organization.test_cases.param_test.example_descr0">Example: 166 Unary class method based test case</a> 167 </h6> 168<div class="informaltable"><table class="table"> 169<colgroup><col></colgroup> 170<thead><tr><th> 171 <p> 172 Code 173 </p> 174 </th></tr></thead> 175<tbody><tr><td> 176<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span> 177<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 178<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">floating_point_comparison</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 179<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">parameterized_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 180<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 181<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span> 182<span class="keyword">namespace</span> <span class="identifier">tt</span><span class="special">=</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span> 183 184 185<span class="keyword">class</span> <span class="identifier">test_class</span> <span class="special">{</span> 186<span class="keyword">public</span><span class="special">:</span> 187 <span class="keyword">void</span> <span class="identifier">test_method</span><span class="special">(</span> <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">)</span> 188 <span class="special">{</span> 189 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">d</span> <span class="special">*</span> <span class="number">100</span> <span class="special">==</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)(</span><span class="keyword">int</span><span class="special">)(</span><span class="identifier">d</span><span class="special">*</span><span class="number">100</span><span class="special">),</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">tolerance</span><span class="special">(</span><span class="number">0.0001</span><span class="special">)</span> <span class="special">);</span> 190 <span class="special">}</span> 191<span class="special">}</span> <span class="identifier">tester</span><span class="special">;</span> 192 193<span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">()</span> 194<span class="special">{</span> 195 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">;</span> 196 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">placeholders</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span> 197 <span class="keyword">double</span> <span class="identifier">params</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1.</span><span class="special">,</span> <span class="number">1.1</span><span class="special">,</span> <span class="number">1.01</span><span class="special">,</span> <span class="number">1.001</span><span class="special">,</span> <span class="number">1.0001</span> <span class="special">};</span> 198 199 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)></span> <span class="identifier">test_method</span> <span class="special">=</span> <span class="identifier">bind</span><span class="special">(</span> <span class="special">&</span><span class="identifier">test_class</span><span class="special">::</span><span class="identifier">test_method</span><span class="special">,</span> <span class="special">&</span><span class="identifier">tester</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span> 200 201 <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span> 202 <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_PARAM_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_method</span><span class="special">,</span> <span class="identifier">params</span><span class="special">,</span> <span class="identifier">params</span><span class="special">+</span><span class="number">5</span> <span class="special">)</span> <span class="special">);</span> 203 204 <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> 205<span class="special">}</span> 206</pre> 207 </td></tr></tbody> 208</table></div> 209<div class="informaltable"><table class="table"> 210<colgroup><col></colgroup> 211<thead><tr><th> 212 <p> 213 Output 214 </p> 215 </th></tr></thead> 216<tbody><tr><td> 217<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> 218<span class="identifier">Running</span> <span class="number">5</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span> 219<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">23</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_method"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">d</span> <span class="special">*</span> <span class="number">100</span> <span class="special">==</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)(</span><span class="keyword">int</span><span class="special">)(</span><span class="identifier">d</span><span class="special">*</span><span class="number">100</span><span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">1.0001</span> <span class="special">*</span> <span class="number">100</span> <span class="special">!=</span> <span class="number">100</span><span class="special">].</span> <span class="identifier">Relative</span> <span class="identifier">difference</span> <span class="identifier">exceeds</span> <span class="identifier">tolerance</span> <span class="special">[</span><span class="number">0.001</span> <span class="special">></span> <span class="number">0.0001</span><span class="special">]</span> 220<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">23</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_method"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">d</span> <span class="special">*</span> <span class="number">100</span> <span class="special">==</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)(</span><span class="keyword">int</span><span class="special">)(</span><span class="identifier">d</span><span class="special">*</span><span class="number">100</span><span class="special">)</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">1.0001</span> <span class="special">*</span> <span class="number">100</span> <span class="special">!=</span> <span class="number">100</span><span class="special">].</span> <span class="identifier">Relative</span> <span class="identifier">difference</span> <span class="identifier">exceeds</span> <span class="identifier">tolerance</span> <span class="special">[</span><span class="number">0.0001</span> <span class="special">></span> <span class="number">0.0001</span><span class="special">]</span> 221 222<span class="special">***</span> <span class="number">2</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span> 223</pre> 224 </td></tr></tbody> 225</table></div> 226</div> 227<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 228<td align="left"></td> 229<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p> 230 Distributed under the Boost Software License, Version 1.0. (See accompanying 231 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 232 </p> 233</div></td> 234</tr></table> 235<hr> 236<div class="spirit-nav"> 237<a accesskey="p" href="test_organization_templates.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_cases.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../test_tree.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 238</div> 239</body> 240</html> 241
