1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Master test suite</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_tree.html" title="Test tree"> 9<link rel="prev" href="test_suite.html" title="Test suite"> 10<link rel="next" href="test_naming.html" title="Tests naming"> 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_suite.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tree.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_naming.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_test.tests_organization.test_tree.master_test_suite"></a><a class="link" href="master_test_suite.html" title="Master test suite">Master 28 test suite</a> 29</h4></div></div></div> 30<p> 31 As defined in introduction section the master test suite is the <span class="bold"><strong>root</strong></span> node of the test tree. Each test module built 32 with the <span class="emphasis"><em>Unit Test Framework</em></span> always has the (unique) 33 master test suite defined. The <span class="emphasis"><em>Unit Test Framework</em></span> 34 maintain the master test suite instance internally. All other test units 35 are registered as direct or indirect children of the master test suite. 36 </p> 37<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 38<span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span> 39<span class="keyword">class</span> <span class="identifier">master_test_suite_t</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">test_suite</span> 40<span class="special">{</span> 41 <span class="comment">/// implementation details</span> 42<span class="keyword">public</span><span class="special">:</span> 43 <span class="keyword">int</span> <span class="identifier">argc</span><span class="special">;</span> 44 <span class="keyword">char</span><span class="special">**</span> <span class="identifier">argv</span><span class="special">;</span> 45<span class="special">};</span> 46 47<span class="special">}</span> <span class="comment">// namespace unit_test</span> 48<span class="special">}</span> <span class="comment">// namespace boost</span> 49</pre> 50<p> 51 To access single instance of the master test suite use the following interface: 52 </p> 53<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 54<span class="keyword">namespace</span> <span class="identifier">unit_test</span> <span class="special">{</span> 55<span class="keyword">namespace</span> <span class="identifier">framework</span> <span class="special">{</span> 56 57<span class="identifier">master_test_suite_t</span><span class="special">&</span> <span class="identifier">master_test_suite</span><span class="special">();</span> 58 59<span class="special">}</span> <span class="comment">// namespace framework</span> 60<span class="special">}</span> <span class="comment">// namespace unit_test</span> 61<span class="special">}</span> <span class="comment">// namespace boost</span> 62</pre> 63<h5> 64<a name="boost_test.tests_organization.test_tree.master_test_suite.h0"></a> 65 <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.command_line_arguments_access_in"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.command_line_arguments_access_in">Command 66 line arguments access interface</a> 67 </h5> 68<p> 69 Master test suite implemented as an extension to the regular test suite, 70 since it maintains references to the command line arguments passed to the 71 test module. To access the command line arguments use 72 </p> 73<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">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> 74<span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">::</span><span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argv</span> 75</pre> 76<p> 77 In below example references to the command line arguments are accessible 78 either as an initialization function parameters or as members of the master 79 test suite. Both references point to the same values. A test module that 80 uses the alternative initialization function specification can only access 81 command line arguments through the master test suite. 82 </p> 83<p> 84 Returning to the free function example, let's modify initialization function 85 to check for absence of any test module arguments. 86 </p> 87<h6> 88<a name="boost_test.tests_organization.test_tree.master_test_suite.h1"></a> 89 <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr">Example: 90 Command line access in initialization function</a> 91 </h6> 92<div class="informaltable"><table class="table"> 93<colgroup><col></colgroup> 94<thead><tr><th> 95 <p> 96 Code 97 </p> 98 </th></tr></thead> 99<tbody><tr><td> 100<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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> 101<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span> 102 103<span class="keyword">void</span> <span class="identifier">free_test_function</span><span class="special">()</span> 104<span class="special">{</span> 105 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span> 106<span class="special">}</span> 107 108<span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span> 109<span class="special">{</span> 110 <span class="keyword">if</span><span class="special">(</span> <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">argc</span> <span class="special">></span> <span class="number">1</span> <span class="special">)</span> 111 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 112 113 <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span> 114 <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&</span><span class="identifier">free_test_function</span> <span class="special">)</span> <span class="special">);</span> 115 116 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 117<span class="special">}</span> 118</pre> 119 </td></tr></tbody> 120</table></div> 121<div class="informaltable"><table class="table"> 122<colgroup><col></colgroup> 123<thead><tr><th> 124 <p> 125 Output 126 </p> 127 </th></tr></thead> 128<tbody><tr><td> 129<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> <span class="number">1</span> 130<span class="identifier">Test</span> <span class="identifier">setup</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">test</span> <span class="identifier">tree</span> <span class="identifier">is</span> <span class="identifier">empty</span> 131</pre> 132 </td></tr></tbody> 133</table></div> 134<a name="ref_BOOST_TEST_MODULE"></a><h5> 135<a name="boost_test.tests_organization.test_tree.master_test_suite.h2"></a> 136 <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.naming_the_master_test_suite"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.naming_the_master_test_suite">Naming 137 the <span class="emphasis"><em>Master test suite</em></span></a> 138 </h5> 139<p> 140 The master test suite is created with default name <span class="emphasis"><em>Master Test 141 Suite</em></span>. There are two methods two reset the name to a different 142 value: using the macro <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> and from within 143 the test module initialization function. Former is used for test modules 144 that don't have the manually implemented initialization function. Following 145 examples illustrate these methods. 146 </p> 147<h6> 148<a name="boost_test.tests_organization.test_tree.master_test_suite.h3"></a> 149 <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr0"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr0">Example: 150 Naming master test suite using the macro <code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> 151 </h6> 152<div class="informaltable"><table class="table"> 153<colgroup><col></colgroup> 154<thead><tr><th> 155 <p> 156 Code 157 </p> 158 </th></tr></thead> 159<tbody><tr><td> 160<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">my</span> <span class="identifier">master</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="identifier">name</span> 161<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> 162 163<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">free_test_function</span> <span class="special">)</span> 164<span class="special">{</span> 165 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span> 166<span class="special">}</span> 167</pre> 168 </td></tr></tbody> 169</table></div> 170<div class="informaltable"><table class="table"> 171<colgroup><col></colgroup> 172<thead><tr><th> 173 <p> 174 Output 175 </p> 176 </th></tr></thead> 177<tbody><tr><td> 178<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span> 179<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span> 180<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span> 181<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span> 182<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span> 183<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span> 184 185<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span> 186</pre> 187 </td></tr></tbody> 188</table></div> 189<p> 190 If the macro <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> is defined, 191 the test module initialization function is <span class="bold"><strong>automatically 192 generated</strong></span> and the macro value becomes the name of the master 193 test suite. The name may include spaces. 194 </p> 195<h6> 196<a name="boost_test.tests_organization.test_tree.master_test_suite.h4"></a> 197 <span class="phrase"><a name="boost_test.tests_organization.test_tree.master_test_suite.example_descr1"></a></span><a class="link" href="master_test_suite.html#boost_test.tests_organization.test_tree.master_test_suite.example_descr1">Example: 198 Naming master test suite explicitly in the test module initialization function</a> 199 </h6> 200<div class="informaltable"><table class="table"> 201<colgroup><col></colgroup> 202<thead><tr><th> 203 <p> 204 Code 205 </p> 206 </th></tr></thead> 207<tbody><tr><td> 208<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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> 209<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span> 210 211<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">free_test_function</span> <span class="special">)</span> 212<span class="special">{</span> 213 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span> 214<span class="special">}</span> 215 216<span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span> 217<span class="special">{</span> 218 <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">p_name</span><span class="special">.</span><span class="identifier">value</span> <span class="special">=</span> <span class="string">"my master test suite name"</span><span class="special">;</span> 219 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 220<span class="special">}</span> 221</pre> 222 </td></tr></tbody> 223</table></div> 224<div class="informaltable"><table class="table"> 225<colgroup><col></colgroup> 226<thead><tr><th> 227 <p> 228 Output 229 </p> 230 </th></tr></thead> 231<tbody><tr><td> 232<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">test_suite</span> 233<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span> 234<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span> 235<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span> 236<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">1</span><span class="identifier">ms</span> 237<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"my master test suite name"</span> 238 239<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span> 240</pre> 241 </td></tr></tbody> 242</table></div> 243<p> 244 Without the <a class="link" href="../../utf_reference/link_references/link_boost_test_main_macro.html" title="BOOST_TEST_MAIN"><code class="computeroutput"><span class="identifier">BOOST_TEST_MAIN</span></code></a> and the <a class="link" href="../../utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> flags defined, 245 the test module initialization function has to be manually implemented. 246 The master test suite name can be reset at any point within this function. 247 </p> 248</div> 249<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 250<td align="left"></td> 251<td align="right"><div class="copyright-footer">Copyright © 2001-2020 Boost.Test contributors<p> 252 Distributed under the Boost Software License, Version 1.0. (See accompanying 253 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>) 254 </p> 255</div></td> 256</tr></table> 257<hr> 258<div class="spirit-nav"> 259<a accesskey="p" href="test_suite.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tree.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="test_naming.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 260</div> 261</body> 262</html> 263
