3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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">
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>
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>
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>
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>
37 A <span class="bold"><strong>dataset</strong></span> is a <span class="emphasis"><em>collection
38 of samples</em></span>, that
40 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
45 can be queried for its <code class="computeroutput"><span class="identifier">size</span></code>
46 which in turn can be infinite,
49 has an arity which is the arity of the samples it contains.
53 Hence the dataset implements the notion of <span class="emphasis"><em>sequence</em></span>.
56 The descriptive power of the datasets in <span class="emphasis"><em>Unit Test Framework</em></span>
59 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
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,
65 the <a class="link" href="operations.html" title="Operations on dataset">operations</a>
66 they provide for combining different datasets
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)
73 the available built-in <a class="link" href="generators.html" title="Datasets generators"><span class="emphasis"><em>dataset
74 generators</em></span></a>
77 <div class="tip"><table border="0" summary="Tip">
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>
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.
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.
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
99 </h6></div></div></div>
101 The interface of the <span class="emphasis"><em>dataset</em></span> should implement
102 the two following functions/fields:
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,
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.
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
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
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>
127 with the condition that
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>
131 evaluates to <code class="computeroutput"><span class="keyword">true</span></code>.
134 The following example implements a custom dataset generating a Fibonacci
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>
142 <div class="informaltable"><table class="table">
143 <colgroup><col></colgroup>
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>
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>
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>
164 <span class="keyword">struct</span> <span class="identifier">iterator</span> <span class="special">{</span>
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>
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>
179 <span class="identifier">fibonacci_dataset</span><span class="special">()</span> <span class="special">{}</span>
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>
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>
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>
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>
205 <div class="informaltable"><table class="table">
206 <colgroup><col></colgroup>
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>
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>
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>
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.
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.
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:
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>
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>.
263 <div class="tip"><table border="0" summary="Tip">
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>
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.
274 <div class="tip"><table border="0" summary="Tip">
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>
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.
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.
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-2019 Boost.Test
298 Distributed under the Boost Software License, Version 1.0. (See accompanying
299 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>)
304 <div class="spirit-nav">
305 <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>