1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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"><=</span> <span class="number">4</span> <span class="special">&&</span> <span class="identifier">sample</span> <span class="special">>=</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"><=</span> <span class="number">4</span> <span class="special">&&</span> <span class="identifier">my_var</span> <span class="special">>=</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"><=</span> <span class="number">1</span> <span class="special">&&</span> <span class="identifier">apples</span> <span class="special">>=</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"><=</span> <span class="number">4</span> <span class="special">&&</span> <span class="identifier">potatoes</span> <span class="special">>=</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 © 2001-2020 Boost.Test contributors<p> 193 Distributed under the Boost Software License, Version 1.0. (See accompanying 194 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>) 195 </p> 196</div></td> 197</tr></table> 198<hr> 199<div class="spirit-nav"> 200<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> 201</div> 202</body> 203</html> 204
