libs/test/doc/html/boost_test/tests_organization/test_cases/test_case_generation/datasets_auto_registration.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Declaring and registering test cases with datasets</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_case_generation.html" title="Data-driven test cases">
   9 <link rel="prev" href="datasets.html" title="Datasets">
  10 <link rel="next" href="operations.html" title="Operations on dataset">
  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="datasets.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_case_generation.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="operations.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h5 class="title">
  27 <a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration"></a><a class="link" href="datasets_auto_registration.html" title="Declaring and registering test cases with datasets">Declaring
  28           and registering test cases with datasets</a>
  29 </h5></div></div></div>
  30 <p>
  31             In order to declare and register a data-driven test-case, the macros
  32             <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a> or <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a> should
  33             be used. Those two forms are equivalent, with the difference that <code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code> supports fixtures.
  34           </p>
  35 <p>
  36             Those macros are variadic and can be used in the following forms:
  37           </p>
  38 <pre class="programlisting"><a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 */</span> <span class="special">}</span>
  39 <span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* datasets of arity 1 */</span> <span class="special">}</span>
  40 <span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">varN</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* datasets of arity N  */</span> <span class="special">}</span>
  41
  42 <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 with fixture */</span> <span class="special">}</span>
  43 <span class="identifier">BOOST_DATA_TEST_CASE_F</span><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity 1 with fixture */</span> <span class="special">}</span>
  44 <span class="identifier">BOOST_DATA_TEST_CASE_F</span><span class="special">(</span><span class="identifier">fixture</span><span class="special">,</span> <span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">,</span> <span class="identifier">var1</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">varN</span><span class="special">)</span> <span class="special">{</span> <span class="comment">/* dataset1 of arity N with fixture */</span> <span class="special">}</span>
  45 </pre>
  46 <p>
  47             The first form of the macro is for datasets of arity 1. The value of
  48             the sample being executed by the test body is available through the automatic
  49             variable <code class="computeroutput"><span class="identifier">sample</span></code> (<code class="computeroutput"><span class="identifier">xrange</span></code> is as its name suggests a range
  50             of values):
  51           </p>
  52 <pre class="programlisting"><span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity1_implicit</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">)</span> <span class="special">)</span>
  53 <span class="special">{</span>
  54   <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">sample</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">sample</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
  55 <span class="special">}</span>
  56 </pre>
  57 <p>
  58             The second form is also for datasets of arity 1, but instead of the variable
  59             <code class="computeroutput"><span class="identifier">sample</span></code>, the current sample
  60             is brought into <code class="computeroutput"><span class="identifier">var1</span></code>:
  61           </p>
  62 <pre class="programlisting"><span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity1</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">),</span> <span class="identifier">my_var</span> <span class="special">)</span>
  63 <span class="special">{</span>
  64   <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">my_var</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">my_var</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
  65 <span class="special">}</span>
  66 </pre>
  67 <p>
  68             The third form is an extension of the previous form for datasets of arity
  69             <code class="computeroutput"><span class="identifier">N</span></code>. The sample being a
  70             polymorphic tuple, each of the variables <code class="computeroutput"><span class="identifier">var1</span></code>,
  71             ..., <code class="computeroutput"><span class="identifier">varN</span></code> corresponds
  72             to the index 1, ... <code class="computeroutput"><span class="identifier">N</span></code>
  73             of the the sample:
  74           </p>
  75 <pre class="programlisting"><span class="comment">// The following definition of the dataset test case throws an exception before the</span>
  76 <span class="comment">// test module starts (zip of non infinite or singleton datasets of different length)</span>
  77 <span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_arity2</span><span class="special">,</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">^</span> <span class="identifier">data</span><span class="special">::</span><span class="identifier">xrange</span><span class="special">(</span><span class="number">5</span><span class="special">),</span> <span class="identifier">apples</span><span class="special">,</span> <span class="identifier">potatoes</span><span class="special">)</span>
  78 <span class="special">{</span>
  79   <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">apples</span> <span class="special">&lt;=</span> <span class="number">1</span> <span class="special">&amp;&amp;</span> <span class="identifier">apples</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
  80   <span class="identifier">BOOST_TEST</span><span class="special">((</span><span class="identifier">potatoes</span> <span class="special">&lt;=</span> <span class="number">4</span> <span class="special">&amp;&amp;</span> <span class="identifier">potatoes</span> <span class="special">&gt;=</span> <span class="number">0</span><span class="special">));</span>
  81 <span class="special">}</span>
  82 </pre>
  83 <p>
  84             The next three forms of declaration, with <code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code>,
  85             are equivalent to the previous ones, with the difference being in the
  86             support of a fixture that is execute before the test body for each sample.
  87             The fixture should follow the expected interface as detailed <a class="link" href="../../fixtures/models.html" title="Fixture models">here</a>.
  88           </p>
  89 <p>
  90             The arity of the dataset and the number of variables should be exactly
  91             the same, the first form being a short-cut for the case of arity 1.
  92           </p>
  93 <div class="tip"><table border="0" summary="Tip">
  94 <tr>
  95 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td>
  96 <th align="left">Tip</th>
  97 </tr>
  98 <tr><td align="left" valign="top"><p>
  99               A compilation-time check is performed on the coherence of the arity
 100               of the dataset and the number of variables <code class="computeroutput"><span class="identifier">var1</span></code>...
 101               <code class="computeroutput"><span class="identifier">varN</span></code>. For compilers
 102               <span class="bold"><strong>without C++11</strong></span> support, the maximal
 103               supported arity is controlled by the macro <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_TEST_DATASET_MAX_ARITY</span></code></a>,
 104               that can be overridden <span class="emphasis"><em>prior</em></span> to including the
 105               <span class="emphasis"><em>Unit Test Framework</em></span> headers.
 106             </p></td></tr>
 107 </table></div>
 108 <div class="caution"><table border="0" summary="Caution">
 109 <tr>
 110 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../../doc/src/images/caution.png"></td>
 111 <th align="left">Caution</th>
 112 </tr>
 113 <tr><td align="left" valign="top"><p>
 114               The macros <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a> and
 115               <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset_fixture.html" title="BOOST_DATA_TEST_CASE_F"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE_F</span></code></a> are
 116               available only for compilers with support for <span class="bold"><strong>variadic
 117               macros</strong></span>.
 118             </p></td></tr>
 119 </table></div>
 120 <h5>
 121 <a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.h0"></a>
 122             <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.samples_and_test_tree"></a></span><a class="link" href="datasets_auto_registration.html#boost_test.tests_organization.test_cases.test_case_generation.datasets_auto_registration.samples_and_test_tree">Samples
 123             and test tree</a>
 124           </h5>
 125 <p>
 126             It should be emphasized that those macros do not declare a single test
 127             case (as <a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a> would do)
 128             but declare and register as many test cases as there are samples in the
 129             dataset given in argument. Each test case runs on exactly <span class="bold"><strong>one</strong></span>
 130             sample of the dataset.
 131           </p>
 132 <p>
 133             More precisely, what
 134           </p>
 135 <pre class="programlisting"><a class="link" href="../../../utf_reference/test_org_reference/test_org_boost_test_dataset.html" title="BOOST_DATA_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_DATA_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">dataset</span><span class="special">)</span></pre>
 136 <p>
 137             does is the following:
 138           </p>
 139 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 140 <li class="listitem">
 141                 it registers a <span class="bold"><strong>test suite</strong></span> named
 142                 "<code class="computeroutput"><span class="identifier">test_case_name</span></code>",
 143               </li>
 144 <li class="listitem">
 145                 it registers as many test cases as they are in "<code class="computeroutput"><span class="identifier">dataset</span></code>", each of which with
 146                 the name corresponding to the index of the sample in the database
 147                 prefixed by <code class="computeroutput"><span class="identifier">_</span></code> and
 148                 starting at index <code class="computeroutput"><span class="number">0</span></code> ("<code class="computeroutput"><span class="identifier">_0</span></code>", "<code class="computeroutput"><span class="identifier">_1</span></code>",
 149                 ... "<code class="computeroutput"><span class="identifier">_</span><span class="special">(</span><span class="identifier">N</span><span class="special">-</span><span class="number">1</span><span class="special">)</span></code>"
 150                 where <code class="computeroutput"><span class="identifier">N</span></code> is the size
 151                 of the dataset)
 152               </li>
 153 </ul></div>
 154 <p>
 155             This make it easy to:
 156           </p>
 157 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 158 <li class="listitem">
 159                 identify which sample is failing (say "<code class="computeroutput"><span class="identifier">test_case_name</span><span class="special">/</span><span class="identifier">_3</span></code>"),
 160               </li>
 161 <li class="listitem">
 162                 replay the test for one or several samples (or the full dataset)
 163                 from the command line using the <a class="link" href="../../../runtime_config/test_unit_filtering.html" title="Test unit filtering">test
 164                 filtering features</a> provided by the <span class="emphasis"><em>Unit Test Framework</em></span>,
 165               </li>
 166 <li class="listitem">
 167                 apply a <a class="link" href="../../decorators/explicit_decorator_declaration.html" title="Explicit decorator declaration">decorator</a>
 168                 to each individual test cases of the dataset, as the decorator would
 169                 apply to the test suite.
 170               </li>
 171 </ul></div>
 172 <p>
 173             Exactly as regular test cases, each test case (associated to a specific
 174             sample) is executed in <span class="emphasis"><em>monitored manner</em></span>:
 175           </p>
 176 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 177 <li class="listitem">
 178                 the test execution are independent: if an error occurs for one sample,
 179                 the remaining samples execution is not affected,
 180               </li>
 181 <li class="listitem">
 182                 in case of error, the <a class="link" href="../../../test_output/test_tools_support_for_logging/contexts.html" title="Contexts">context</a>
 183                 along with the index of the sample within which the error occurred
 184                 is reported in the <a class="link" href="../../../test_output.html" title="Controlling outputs">log</a>.
 185                 This context contains the sample names and values for which the test
 186                 failed, which would ease the debugging.
 187               </li>
 188 </ul></div>
 189 </div>
 190 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 191 <td align="left"></td>
 192 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 193       contributors<p>
 194         Distributed under the Boost Software License, Version 1.0. (See accompanying
 195         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>)
 196       </p>
 197 </div></td>
 198 </tr></table>
 199 <hr>
 200 <div class="spirit-nav">
 201 <a accesskey="p" href="datasets.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_case_generation.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="operations.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
 202 </div>
 203 </body>
 204 </html>