1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>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="../test_case_generation.html" title="Data-driven test cases"> 10<link rel="next" href="datasets_auto_registration.html" title="Declaring and registering test cases with datasets"> 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_case_generation.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="datasets_auto_registration.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"></a><a class="link" href="datasets.html" title="Datasets">Datasets</a> 28</h5></div></div></div> 29<p> 30 To define properly datasets, the notion of <span class="bold"><strong>sample</strong></span> 31 should be introduced first. A <span class="bold"><strong>sample</strong></span> 32 is defined as <span class="emphasis"><em>polymorphic tuple</em></span>. The size of the 33 tuple will be by definition the <span class="bold"><strong>arity</strong></span> 34 of the sample itself. 35 </p> 36<p> 37 A <span class="bold"><strong>dataset</strong></span> is a <span class="emphasis"><em>collection 38 of samples</em></span>, that 39 </p> 40<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 41<li class="listitem"> 42 is forward iterable, 43 </li> 44<li class="listitem"> 45 can be queried for its <code class="computeroutput"><span class="identifier">size</span></code> 46 which in turn can be infinite, 47 </li> 48<li class="listitem"> 49 has an arity which is the arity of the samples it contains. 50 </li> 51</ul></div> 52<p> 53 Hence the dataset implements the notion of <span class="emphasis"><em>sequence</em></span>. 54 </p> 55<p> 56 The descriptive power of the datasets in <span class="emphasis"><em>Unit Test Framework</em></span> 57 comes from 58 </p> 59<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 60<li class="listitem"> 61 the <a class="link" href="datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface" title="Dataset interface">interface</a> 62 for creating a custom datasets, which is quite simple, 63 </li> 64<li class="listitem"> 65 the <a class="link" href="operations.html" title="Operations on dataset">operations</a> 66 they provide for combining different datasets 67 </li> 68<li class="listitem"> 69 their interface with other type of collections (<code class="computeroutput"><span class="identifier">stl</span></code> 70 containers, <code class="computeroutput"><span class="identifier">C</span></code> arrays) 71 </li> 72<li class="listitem"> 73 the available built-in <a class="link" href="generators.html" title="Datasets generators"><span class="emphasis"><em>dataset 74 generators</em></span></a> 75 </li> 76</ul></div> 77<div class="tip"><table border="0" summary="Tip"> 78<tr> 79<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td> 80<th align="left">Tip</th> 81</tr> 82<tr><td align="left" valign="top"><p> 83 Only "monomorphic" datasets are supported, which means that 84 all samples within a single dataset have the same type and same arity 85 <a href="#ftn.boost_test.tests_organization.test_cases.test_case_generation.datasets.f0" class="footnote" name="boost_test.tests_organization.test_cases.test_case_generation.datasets.f0"><sup class="footnote">[2]</sup></a> . However, dataset of different sample types may be combined 86 together with zip and cartesian product. 87 </p></td></tr> 88</table></div> 89<p> 90 As we will see in the next sections, datasets representing collections 91 of different types may be combined together (e.g.. <span class="emphasis"><em>zip</em></span> 92 or <span class="emphasis"><em>grid</em></span>). These operations result in new datasets, 93 in which the samples are of an augmented type. 94 </p> 95<div class="section"> 96<div class="titlepage"><div><div><h6 class="title"> 97<a name="boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface"></a><a class="link" href="datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface" title="Dataset interface">Dataset 98 interface</a> 99</h6></div></div></div> 100<p> 101 The interface of the <span class="emphasis"><em>dataset</em></span> should implement 102 the two following functions/fields: 103 </p> 104<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 105<li class="listitem"> 106 <code class="computeroutput"><span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">()</span></code> where <span class="emphasis"><em>iterator</em></span> 107 is a forward iterator, 108 </li> 109<li class="listitem"> 110 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">()</span> <span class="keyword">const</span></code> 111 indicates the size of the dataset. The returned type is a dedicated 112 class <code class="computeroutput"><a class="link" href="../../../../boost/unit_test/data/size_t.html" title="Class size_t">size_t</a></code> 113 that can indicate an <span class="emphasis"><em>infinite</em></span> dataset size. 114 </li> 115<li class="listitem"> 116 an enum called <code class="computeroutput"><span class="identifier">arity</span></code> 117 indicating the arity of the samples returned by the dataset 118 </li> 119</ul></div> 120<p> 121 Once a dataset class <code class="computeroutput"><span class="identifier">D</span></code> 122 is declared, it should be registered to the framework by specializing 123 the template class 124 </p> 125<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">monomorphic</span><span class="special">::</span><span class="identifier">is_dataset</span></pre> 126<p> 127 with the condition that 128 </p> 129<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">monomorphic</span><span class="special">::</span><span class="identifier">is_dataset</span><span class="special"><</span><span class="identifier">D</span><span class="special">>::</span><span class="identifier">value</span></pre> 130<p> 131 evaluates to <code class="computeroutput"><span class="keyword">true</span></code>. 132 </p> 133<p> 134 The following example implements a custom dataset generating a Fibonacci 135 sequence. 136 </p> 137<h6> 138<a name="boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface.h0"></a> 139 <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface.example_descr"></a></span><a class="link" href="datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_interface.example_descr">Example: 140 Example of custom dataset</a> 141 </h6> 142<div class="informaltable"><table class="table"> 143<colgroup><col></colgroup> 144<thead><tr><th> 145 <p> 146 Code 147 </p> 148 </th></tr></thead> 149<tbody><tr><td> 150<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_MODULE</span> <span class="identifier">dataset_example68</span> 151<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> 152<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">data</span><span class="special">/</span><span class="identifier">test_case</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 153<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">data</span><span class="special">/</span><span class="identifier">monomorphic</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 154<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">sstream</span><span class="special">></span> 155 156<span class="keyword">namespace</span> <span class="identifier">bdata</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">;</span> 157 158<span class="comment">// Dataset generating a Fibonacci sequence</span> 159<span class="keyword">class</span> <span class="identifier">fibonacci_dataset</span> <span class="special">{</span> 160<span class="keyword">public</span><span class="special">:</span> 161 <span class="comment">// the type of the samples is deduced</span> 162 <span class="keyword">enum</span> <span class="special">{</span> <span class="identifier">arity</span> <span class="special">=</span> <span class="number">1</span> <span class="special">};</span> 163 164 <span class="keyword">struct</span> <span class="identifier">iterator</span> <span class="special">{</span> 165 166 <span class="identifier">iterator</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">a</span><span class="special">(</span><span class="number">1</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">{}</span> 167 168 <span class="keyword">int</span> <span class="keyword">operator</span><span class="special">*()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span> 169 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">++()</span> 170 <span class="special">{</span> 171 <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span><span class="special">;</span> 172 <span class="identifier">std</span><span class="special">::</span><span class="identifier">swap</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span> 173 <span class="special">}</span> 174 <span class="keyword">private</span><span class="special">:</span> 175 <span class="keyword">int</span> <span class="identifier">a</span><span class="special">;</span> 176 <span class="keyword">int</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// b is the output</span> 177 <span class="special">};</span> 178 179 <span class="identifier">fibonacci_dataset</span><span class="special">()</span> <span class="special">{}</span> 180 181 <span class="comment">// size is infinite</span> 182 <span class="identifier">bdata</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">size</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">bdata</span><span class="special">::</span><span class="identifier">BOOST_TEST_DS_INFINITE_SIZE</span><span class="special">;</span> <span class="special">}</span> 183 184 <span class="comment">// iterator</span> 185 <span class="identifier">iterator</span> <span class="identifier">begin</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">iterator</span><span class="special">();</span> <span class="special">}</span> 186<span class="special">};</span> 187 188<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">data</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">monomorphic</span> <span class="special">{</span> 189 <span class="comment">// registering fibonacci_dataset as a proper dataset</span> 190 <span class="keyword">template</span> <span class="special"><></span> 191 <span class="keyword">struct</span> <span class="identifier">is_dataset</span><span class="special"><</span><span class="identifier">fibonacci_dataset</span><span class="special">></span> <span class="special">:</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> <span class="special">{};</span> 192<span class="special">}}}}</span> 193 194<span class="comment">// Creating a test-driven dataset, the zip is for checking</span> 195<span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span> 196 <span class="identifier">test1</span><span class="special">,</span> 197 <span class="identifier">fibonacci_dataset</span><span class="special">()</span> <span class="special">^</span> <span class="identifier">bdata</span><span class="special">::</span><span class="identifier">make</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">5</span><span class="special">,</span> <span class="number">8</span><span class="special">,</span> <span class="number">13</span><span class="special">,</span> <span class="number">21</span><span class="special">,</span> <span class="number">35</span><span class="special">,</span> <span class="number">56</span> <span class="special">}</span> <span class="special">),</span> 198 <span class="identifier">fib_sample</span><span class="special">,</span> <span class="identifier">exp</span><span class="special">)</span> 199<span class="special">{</span> 200 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">fib_sample</span> <span class="special">==</span> <span class="identifier">exp</span><span class="special">);</span> 201<span class="special">}</span> 202</pre> 203 </td></tr></tbody> 204</table></div> 205<div class="informaltable"><table class="table"> 206<colgroup><col></colgroup> 207<thead><tr><th> 208 <p> 209 Output 210 </p> 211 </th></tr></thead> 212<tbody><tr><td> 213<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example68</span> 214<span class="identifier">Running</span> <span class="number">9</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span> 215<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">60</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test1/_7"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">fib_sample</span> <span class="special">==</span> <span class="identifier">exp</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">34</span> <span class="special">!=</span> <span class="number">35</span><span class="special">]</span> 216<span class="identifier">Failure</span> <span class="identifier">occurred</span> <span class="identifier">in</span> <span class="identifier">a</span> <span class="identifier">following</span> <span class="identifier">context</span><span class="special">:</span> 217 <span class="identifier">fib_sample</span> <span class="special">=</span> <span class="number">34</span><span class="special">;</span> <span class="identifier">exp</span> <span class="special">=</span> <span class="number">35</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">60</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test1/_8"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">fib_sample</span> <span class="special">==</span> <span class="identifier">exp</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">55</span> <span class="special">!=</span> <span class="number">56</span><span class="special">]</span> 219<span class="identifier">Failure</span> <span class="identifier">occurred</span> <span class="identifier">in</span> <span class="identifier">a</span> <span class="identifier">following</span> <span class="identifier">context</span><span class="special">:</span> 220 <span class="identifier">fib_sample</span> <span class="special">=</span> <span class="number">55</span><span class="special">;</span> <span class="identifier">exp</span> <span class="special">=</span> <span class="number">56</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">"dataset_example68"</span> 223</pre> 224 </td></tr></tbody> 225</table></div> 226</div> 227<div class="section"> 228<div class="titlepage"><div><div><h6 class="title"> 229<a name="boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_creation_and_delayed_cre"></a><a class="link" href="datasets.html#boost_test.tests_organization.test_cases.test_case_generation.datasets.dataset_creation_and_delayed_cre" title="Dataset creation and delayed creation">Dataset 230 creation and delayed creation</a> 231</h6></div></div></div> 232<p> 233 Datasets as defined above are constructed before even the test module 234 starts its execution as global objects. This makes impossible to access, 235 from within the dataset generator and during their iteration, elements 236 like <code class="computeroutput"><span class="identifier">argc</span></code> / <code class="computeroutput"><span class="identifier">argv</span></code>, the <a class="link" href="../../test_tree/master_test_suite.html" title="Master test suite">master 237 test suite</a> (and the preprocessed <code class="computeroutput"><span class="identifier">argc</span></code> 238 / <code class="computeroutput"><span class="identifier">argv</span></code>), or any other 239 object that has been instantiated after the <code class="computeroutput"><span class="identifier">main</span></code> 240 of the test module entry. 241 </p> 242<p> 243 To overcome this, a <span class="bold"><strong>delayed</strong></span> dataset 244 instantiation interface has been introduced. This effectively wraps 245 the dataset inside another one, which <span class="bold"><strong>lazyly</strong></span> 246 instantiates the dataset. 247 </p> 248<p> 249 To instantiate a delayed dataset, the <code class="computeroutput">boost::unit_test::data::monomorphic::make_delayed</code> 250 function should be used in the <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> call. 251 The following snippet: 252 </p> 253<pre class="programlisting"><span class="identifier">BOOST_DATA_TEST_CASE</span><span class="special">(</span><span class="identifier">dataset_test_case</span><span class="special">,</span> 254 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">data</span><span class="special">::</span><span class="identifier">make_delayed</span><span class="special"><</span><span class="identifier">custom_dataset</span><span class="special">>(</span><span class="identifier">arg1</span><span class="special">,</span> <span class="special">...</span> <span class="special">),</span> <span class="special">...)</span> 255<span class="special">{</span> 256<span class="special">}</span> 257</pre> 258<p> 259 creates a delayed dataset test case with a generator of type <code class="computeroutput"><span class="identifier">custom_dataset</span></code>. The generator is 260 <span class="emphasis"><em>lazily</em></span> constructed with <code class="computeroutput"><span class="identifier">arg1</span></code>, 261 <code class="computeroutput"><span class="special">...</span></code>. 262 </p> 263<div class="tip"><table border="0" summary="Tip"> 264<tr> 265<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td> 266<th align="left">Tip</th> 267</tr> 268<tr><td align="left" valign="top"><p> 269 A detailed example of delayed creation is given in the section about 270 <a class="link" href="../../../runtime_config/custom_command_line_arguments.html" title="Custom command line arguments">custom 271 command line</a> arguments. 272 </p></td></tr> 273</table></div> 274<div class="tip"><table border="0" summary="Tip"> 275<tr> 276<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td> 277<th align="left">Tip</th> 278</tr> 279<tr><td align="left" valign="top"><p> 280 See the class <code class="computeroutput"><a class="link" href="../../../../boost/unit_test/data/monomorphic/delayed_dataset.html" title="Class template delayed_dataset">monomorphic::delayed_dataset</a></code> for 281 more details on the wrapping object. 282 </p></td></tr> 283</table></div> 284</div> 285<div class="footnotes"> 286<br><hr style="width:100; text-align:left;margin-left: 0"> 287<div id="ftn.boost_test.tests_organization.test_cases.test_case_generation.datasets.f0" class="footnote"><p><a href="#boost_test.tests_organization.test_cases.test_case_generation.datasets.f0" class="para"><sup class="para">[2] </sup></a> 288 polymorphic datasets will be considered in the future. Their need 289 is mainly driven by the replacement of the <a class="link" href="../test_organization_templates.html" title="Template test cases">typed 290 parametrized test cases</a> by the dataset-like API. 291 </p></div> 292</div> 293</div> 294<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 295<td align="left"></td> 296<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p> 297 Distributed under the Boost Software License, Version 1.0. (See accompanying 298 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>) 299 </p> 300</div></td> 301</tr></table> 302<hr> 303<div class="spirit-nav"> 304<a accesskey="p" href="../test_case_generation.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="datasets_auto_registration.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 305</div> 306</body> 307</html> 308
