libs/test/doc/html/boost_test/tests_organization/test_cases/param_test.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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_suite.html" title="Test suite">
  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_suite.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">&amp;</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#idp57979136-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 &lt;boost/test/parameterized_test.hpp&gt;">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">&lt;</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">&gt;</span>
 119 <span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</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">&lt;</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">&amp;</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">&gt;</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">&lt;</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">&gt;=</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">&lt;</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">&gt;=</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">&lt;</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">&gt;</span>
 178 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">floating_point_comparison</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 179 <span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
 180 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</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 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span>
 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">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>
 196
 197   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span><span class="special">&lt;</span><span class="keyword">void</span> <span class="special">(</span><span class="keyword">double</span><span class="special">)&gt;</span> <span class="identifier">test_method</span> <span class="special">=</span> <span class="identifier">bind</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_class</span><span class="special">::</span><span class="identifier">test_method</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">tester</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">);</span>
 198
 199   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 200     <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>
 201
 202   <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
 203 <span class="special">}</span>
 204 </pre>
 205                 </td></tr></tbody>
 206 </table></div>
 207 <div class="informaltable"><table class="table">
 208 <colgroup><col></colgroup>
 209 <thead><tr><th>
 210                   <p>
 211                     Output
 212                   </p>
 213                 </th></tr></thead>
 214 <tbody><tr><td>
 215 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
 216 <span class="identifier">Running</span> <span class="number">5</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 217 <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">&gt;</span> <span class="number">0.0001</span><span class="special">]</span>
 218 <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">&gt;</span> <span class="number">0.0001</span><span class="special">]</span>
 219
 220 <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>
 221 </pre>
 222                 </td></tr></tbody>
 223 </table></div>
 224 </div>
 225 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 226 <td align="left"></td>
 227 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2016 Boost.Test contributors<p>
 228         Distributed under the Boost Software License, Version 1.0. (See accompanying
 229         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>)
 230       </p>
 231 </div></td>
 232 </tr></table>
 233 <hr>
 234 <div class="spirit-nav">
 235 <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_suite.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 236 </div>
 237 </body>
 238 </html>