libs/test/doc/html/boost_test/tests_organization/test_tree/test_suite.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>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_tree.html" title="Test tree">
  10 <link rel="next" href="master_test_suite.html" title="Master test suite">
  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_tree.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="master_test_suite.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.test_suite"></a><a class="link" href="test_suite.html" title="Test suite">Test
  28         suite</a>
  29 </h4></div></div></div>
  30 <p>
  31           If you consider test cases as leaves on the test tree, the test suite can
  32           be considered as branch and the <span class="emphasis"><em>master test suite</em></span>
  33           as the <span class="emphasis"><em>root</em></span>. Unlike real trees though, our tree in
  34           many cases consists only of leaves attached directly to the root. This
  35           is common for all test cases to reside directly in the master test suite.
  36           If you do want to construct a hierarchical test suite structure the <span class="emphasis"><em>Unit
  37           Test Framework</em></span> provides both manual and automated test suite
  38           creation and registration facilities:
  39         </p>
  40 <div class="orderedlist"><ol class="orderedlist" type="1">
  41 <li class="listitem">
  42               Test suite with automated registration
  43             </li>
  44 <li class="listitem">
  45               Manually registered test suite
  46             </li>
  47 </ol></div>
  48 <p>
  49           In addition the <span class="emphasis"><em>Unit Test Framework</em></span> presents a notion
  50           of the <a class="link" href="master_test_suite.html" title="Master test suite">Master
  51           test suite</a>. The most important reason to learn about this component
  52           is that it provides an ability to access command line arguments supplied
  53           to a test module.
  54         </p>
  55 <a name="ref_BOOST_AUTO_TEST_SUITE"></a><h4>
  56 <a name="boost_test.tests_organization.test_tree.test_suite.h0"></a>
  57           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.automated_registration"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.automated_registration">Automated
  58           registration</a>
  59         </h4>
  60 <p>
  61           The solution the <span class="emphasis"><em>Unit Test Framework</em></span> presents for
  62           automated test suite creation and registration is designed to facilitate
  63           multiple points of definition, arbitrary test suites depth and smooth integration
  64           with automated test case creation and registration. This facility should
  65           significantly simplify a test tree construction process in comparison with
  66           manual explicit registration case.
  67         </p>
  68 <p>
  69           The implementation is based on the order of file scope variables definitions
  70           within a single compilation unit. The semantic of this facility is very
  71           similar to the namespace feature of C++, including support for test suite
  72           extension. To start test suite use the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_suite.html" title="BOOST_AUTO_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_SUITE</span></code></a>. To end
  73           test suite use the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_suite_end.html" title="BOOST_AUTO_TEST_SUITE_END"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_SUITE_END</span></code></a>. The
  74           same test suite can be restarted multiple times inside the same test file
  75           or in a different test files. In a result all test units will be part of
  76           the same test suite in a constructed test tree.
  77         </p>
  78 <pre class="programlisting"><span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">test_suite_name</span><span class="special">);</span>
  79 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">();</span>
  80 </pre>
  81 <p>
  82           Test units defined in between test suite start and end declarations become
  83           members of the test suite. A test unit always becomes the member of the
  84           closest test suite declared. Test units declared at a test file scope become
  85           members of the master test suite. There is no limit on depth of test suite
  86           inclusion.
  87         </p>
  88 <p>
  89           This example creates a test tree that matches exactly the one created in
  90           the manual test suite registration example.
  91         </p>
  92 <h6>
  93 <a name="boost_test.tests_organization.test_tree.test_suite.h1"></a>
  94           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.example_descr"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.example_descr">Example:
  95           Test suites with automated registration</a>
  96         </h6>
  97 <div class="informaltable"><table class="table">
  98 <colgroup><col></colgroup>
  99 <thead><tr><th>
 100                   <p>
 101                     Code
 102                   </p>
 103                 </th></tr></thead>
 104 <tbody><tr><td>
 105 <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">example</span>
 106 <span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
 107
 108 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite1</span> <span class="special">)</span>
 109
 110 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case1</span> <span class="special">)</span>
 111 <span class="special">{</span>
 112   <span class="identifier">BOOST_TEST_WARN</span><span class="special">(</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span> <span class="special">&lt;</span> <span class="number">4U</span> <span class="special">);</span>
 113 <span class="special">}</span>
 114
 115 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case2</span> <span class="special">)</span>
 116 <span class="special">{</span>
 117   <span class="identifier">BOOST_TEST_REQUIRE</span><span class="special">(</span> <span class="number">1</span> <span class="special">==</span> <span class="number">2</span> <span class="special">);</span>
 118   <span class="identifier">BOOST_FAIL</span><span class="special">(</span> <span class="string">"Should never reach this line"</span> <span class="special">);</span>
 119 <span class="special">}</span>
 120
 121 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 122 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite2</span> <span class="special">)</span>
 123
 124 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case3</span> <span class="special">)</span>
 125 <span class="special">{</span>
 126   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span>
 127 <span class="special">}</span>
 128
 129 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case4</span> <span class="special">)</span>
 130 <span class="special">{</span>
 131   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">);</span>
 132 <span class="special">}</span>
 133
 134 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 135 </pre>
 136                 </td></tr></tbody>
 137 </table></div>
 138 <div class="informaltable"><table class="table">
 139 <colgroup><col></colgroup>
 140 <thead><tr><th>
 141                   <p>
 142                     Output
 143                   </p>
 144                 </th></tr></thead>
 145 <tbody><tr><td>
 146 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
 147 <span class="identifier">Running</span> <span class="number">4</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 148 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">21</span><span class="special">):</span> <span class="identifier">fatal</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_suite1/test_case2"</span><span class="special">:</span> <span class="identifier">critical</span> <span class="identifier">check</span> <span class="number">1</span> <span class="special">==</span> <span class="number">2</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">1</span> <span class="special">!=</span> <span class="number">2</span><span class="special">]</span>
 149 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">35</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_suite2/test_case4"</span><span class="special">:</span> <span class="identifier">check</span> <span class="keyword">false</span> <span class="identifier">has</span> <span class="identifier">failed</span>
 150
 151 <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">"example"</span>
 152 </pre>
 153                 </td></tr></tbody>
 154 </table></div>
 155 <p>
 156           As you can see test tree construction in this example is more straightforward
 157           and automated.
 158         </p>
 159 <p>
 160           In the example below, the test suite <code class="computeroutput"><span class="identifier">test_suite</span></code>
 161           consists of two parts. Their definition is remote and is separated by another
 162           test case. In fact these parts may even reside in different test files.
 163           The resulting test tree remains the same. As you can see from the output
 164           both <code class="computeroutput"><span class="identifier">test_case1</span></code> and <code class="computeroutput"><span class="identifier">test_case2</span></code> reside in the same test suite
 165           <code class="computeroutput"><span class="identifier">test_suite</span></code>.
 166         </p>
 167 <h6>
 168 <a name="boost_test.tests_organization.test_tree.test_suite.h2"></a>
 169           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.example_descr0"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.example_descr0">Example:
 170           Test suite extension using automated registration facility</a>
 171         </h6>
 172 <div class="informaltable"><table class="table">
 173 <colgroup><col></colgroup>
 174 <thead><tr><th>
 175                   <p>
 176                     Code
 177                   </p>
 178                 </th></tr></thead>
 179 <tbody><tr><td>
 180 <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">example</span>
 181 <span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
 182
 183 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite</span> <span class="special">)</span>
 184
 185 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case1</span> <span class="special">)</span>
 186 <span class="special">{</span>
 187   <span class="identifier">BOOST_ERROR</span><span class="special">(</span> <span class="string">"some error 1"</span> <span class="special">);</span>
 188 <span class="special">}</span>
 189
 190 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 191
 192
 193 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case_on_file_scope</span> <span class="special">)</span>
 194 <span class="special">{</span>
 195   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span>
 196 <span class="special">}</span>
 197
 198 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite</span> <span class="special">)</span>
 199
 200 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case2</span> <span class="special">)</span>
 201 <span class="special">{</span>
 202   <span class="identifier">BOOST_ERROR</span><span class="special">(</span> <span class="string">"some error 2"</span> <span class="special">);</span>
 203 <span class="special">}</span>
 204
 205 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 206 </pre>
 207                 </td></tr></tbody>
 208 </table></div>
 209 <div class="informaltable"><table class="table">
 210 <colgroup><col></colgroup>
 211 <thead><tr><th>
 212                   <p>
 213                     Output
 214                   </p>
 215                 </th></tr></thead>
 216 <tbody><tr><td>
 217 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span><span class="identifier">example</span> <span class="special">--</span><span class="identifier">report_level</span><span class="special">=</span><span class="identifier">detailed</span>
 218 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 219 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">8</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_case1"</span><span class="special">:</span> <span class="identifier">some</span> <span class="identifier">error</span> <span class="number">1</span>
 220 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">23</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_case2"</span><span class="special">:</span> <span class="identifier">some</span> <span class="identifier">error</span> <span class="number">2</span>
 221
 222 <span class="identifier">Test</span> <span class="identifier">suite</span> <span class="string">"example"</span> <span class="identifier">failed</span> <span class="identifier">with</span><span class="special">:</span>
 223   <span class="number">1</span> <span class="identifier">assertion</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">3</span> <span class="identifier">passed</span>
 224   <span class="number">2</span> <span class="identifier">assertions</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">3</span> <span class="identifier">failed</span>
 225   <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">3</span> <span class="identifier">passed</span>
 226   <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">3</span> <span class="identifier">failed</span>
 227
 228   <span class="identifier">Test</span> <span class="identifier">suite</span> <span class="string">"test_suite"</span> <span class="identifier">failed</span> <span class="identifier">with</span><span class="special">:</span>
 229     <span class="number">2</span> <span class="identifier">assertions</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">2</span> <span class="identifier">failed</span>
 230     <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">2</span> <span class="identifier">failed</span>
 231
 232     <span class="identifier">Test</span> <span class="keyword">case</span> <span class="string">"test_case1"</span> <span class="identifier">failed</span> <span class="identifier">with</span><span class="special">:</span>
 233       <span class="number">1</span> <span class="identifier">assertion</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">1</span> <span class="identifier">failed</span>
 234
 235     <span class="identifier">Test</span> <span class="keyword">case</span> <span class="string">"test_case2"</span> <span class="identifier">failed</span> <span class="identifier">with</span><span class="special">:</span>
 236       <span class="number">1</span> <span class="identifier">assertion</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">1</span> <span class="identifier">failed</span>
 237
 238   <span class="identifier">Test</span> <span class="keyword">case</span> <span class="string">"test_case_on_file_scope"</span> <span class="identifier">passed</span> <span class="identifier">with</span><span class="special">:</span>
 239     <span class="number">1</span> <span class="identifier">assertion</span> <span class="identifier">out</span> <span class="identifier">of</span> <span class="number">1</span> <span class="identifier">passed</span>
 240 </pre>
 241                 </td></tr></tbody>
 242 </table></div>
 243 <h4>
 244 <a name="boost_test.tests_organization.test_tree.test_suite.h3"></a>
 245           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.test_suites_with_manual_registra"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.test_suites_with_manual_registra">Test
 246           suites with manual registration</a>
 247         </h4>
 248 <p>
 249           To create a test suite manually you need to
 250         </p>
 251 <div class="orderedlist"><ol class="orderedlist" type="1">
 252 <li class="listitem">
 253               create an instance of <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html" title="Class test_suite">boost::unit_test::test_suite</a></code>
 254               class,
 255             </li>
 256 <li class="listitem">
 257               register it in test tree, and
 258             </li>
 259 <li class="listitem">
 260               populate it with test cases (or lower level test suites).
 261             </li>
 262 </ol></div>
 263 <a name="ref_test_case_registration"></a><h5>
 264 <a name="boost_test.tests_organization.test_tree.test_suite.h4"></a>
 265           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.test_unit_registration_interface"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.test_unit_registration_interface">Test
 266           unit registration interface</a>
 267         </h5>
 268 <p>
 269           The <span class="emphasis"><em>Unit Test Framework</em></span> models the notion of test
 270           case container - test suite - using class <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html" title="Class test_suite">boost::unit_test::test_suite</a></code>.
 271           For complete class interface reference check advanced section of this documentation.
 272           Here you should only be interested in a single test unit registration interface:
 273         </p>
 274 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">test_suite</span><span class="special">::</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">test_unit</span><span class="special">*</span> <span class="identifier">tc</span><span class="special">,</span> <span class="identifier">counter_t</span> <span class="identifier">expected_failures</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">timeout</span> <span class="special">=</span> <span class="number">0</span> <span class="special">);</span>
 275 </pre>
 276 <p>
 277           The first parameter is a pointer to a newly created test unit. The second
 278           optional parameter - expected_failures - defines the number of test assertions
 279           that are expected to fail within the test unit. By default no errors are
 280           expected.
 281         </p>
 282 <div class="caution"><table border="0" summary="Caution">
 283 <tr>
 284 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
 285 <th align="left">Caution</th>
 286 </tr>
 287 <tr><td align="left" valign="top"><p>
 288             Be careful when supplying a number of expected failures for test suites.
 289             By default the <span class="emphasis"><em>Unit Test Framework</em></span> calculates the
 290             number of expected failures in test suite as the sum of appropriate values
 291             in all test units that constitute it. And it rarely makes sense to change
 292             this.
 293           </p></td></tr>
 294 </table></div>
 295 <p>
 296           The third optional parameter - <code class="computeroutput"><span class="identifier">timeout</span></code>
 297           - defines the timeout value for the test unit. As of now the <span class="emphasis"><em>Unit
 298           Test Framework</em></span> isn't able to set a timeout for the test suite
 299           execution, so this parameter makes sense only for test case registration.
 300           By default no timeout is set. See the method <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html#idm46279112866240-bb">boost::unit_test::test_suite::add</a></code>
 301           for more details about the timeout value.
 302         </p>
 303 <p>
 304           To register group of test units in one function call, the <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html" title="Class test_suite">test_suite</a></code> class provides
 305           another <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html#idm46279112866240-bb">add</a></code> interface covered in
 306           the advanced section of this documentation.
 307         </p>
 308 <a name="ref_BOOST_TEST_SUITE"></a><h5>
 309 <a name="boost_test.tests_organization.test_tree.test_suite.h5"></a>
 310           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.test_suite_instance_construction"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.test_suite_instance_construction">Test
 311           suite instance construction</a>
 312         </h5>
 313 <p>
 314           To create a test suite instance manually, employ the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_suite.html" title="BOOST_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_TEST_SUITE</span></code></a>. It hides all
 315           implementation details and you only required to specify the test suite
 316           name:
 317         </p>
 318 <pre class="programlisting"><span class="identifier">BOOST_TEST_SUITE</span><span class="special">(</span><span class="identifier">test_suite_name</span><span class="special">);</span>
 319 </pre>
 320 <p>
 321           <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_suite.html" title="BOOST_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_TEST_SUITE</span></code></a> creates an instance
 322           of the class <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">test_suite</span></code> and returns a pointer to the
 323           constructed instance. Alternatively you can create an instance of class
 324           <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">test_suite</span></code> yourself.
 325         </p>
 326 <div class="caution"><table border="0" summary="Caution">
 327 <tr>
 328 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
 329 <th align="left">Caution</th>
 330 </tr>
 331 <tr><td align="left" valign="top"><p>
 332             <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">test_suite</span></code> instances have to be allocated
 333             on the heap and the compiler won't allow you to create one on the stack.
 334           </p></td></tr>
 335 </table></div>
 336 <p>
 337           Newly created test suite has to be registered in a parent one using the
 338           <code class="computeroutput"><span class="identifier">add</span></code> interface. Both test
 339           suite creation and registration is performed in the test module initialization
 340           function.
 341         </p>
 342 <p>
 343           The example below creates a test tree, which can be represented by the
 344           following hierarchy:
 345         </p>
 346 <p>
 347           <span class="inlinemediaobject"><img src="../../../images/class-hier.jpg"></span>
 348         </p>
 349 <h6>
 350 <a name="boost_test.tests_organization.test_tree.test_suite.h6"></a>
 351           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_suite.example_descr1"></a></span><a class="link" href="test_suite.html#boost_test.tests_organization.test_tree.test_suite.example_descr1">Example:
 352           Manually registered test suites</a>
 353         </h6>
 354 <div class="informaltable"><table class="table">
 355 <colgroup><col></colgroup>
 356 <thead><tr><th>
 357                   <p>
 358                     Code
 359                   </p>
 360                 </th></tr></thead>
 361 <tbody><tr><td>
 362 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
 363 <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>
 364
 365 <span class="keyword">void</span> <span class="identifier">test_case1</span><span class="special">()</span> <span class="special">{</span> <span class="comment">/* ... */</span> <span class="special">}</span>
 366 <span class="keyword">void</span> <span class="identifier">test_case2</span><span class="special">()</span> <span class="special">{</span> <span class="comment">/* ... */</span> <span class="special">}</span>
 367 <span class="keyword">void</span> <span class="identifier">test_case3</span><span class="special">()</span> <span class="special">{</span> <span class="comment">/* ... */</span> <span class="special">}</span>
 368 <span class="keyword">void</span> <span class="identifier">test_case4</span><span class="special">()</span> <span class="special">{</span> <span class="comment">/* ... */</span> <span class="special">}</span>
 369
 370 <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>
 371 <span class="special">{</span>
 372   <span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">ts1</span> <span class="special">=</span> <span class="identifier">BOOST_TEST_SUITE</span><span class="special">(</span> <span class="string">"test_suite1"</span> <span class="special">);</span>
 373   <span class="identifier">ts1</span><span class="special">-&gt;</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_case1</span> <span class="special">)</span> <span class="special">);</span>
 374   <span class="identifier">ts1</span><span class="special">-&gt;</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_case2</span> <span class="special">)</span> <span class="special">);</span>
 375
 376   <span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">ts2</span> <span class="special">=</span> <span class="identifier">BOOST_TEST_SUITE</span><span class="special">(</span> <span class="string">"test_suite2"</span> <span class="special">);</span>
 377   <span class="identifier">ts2</span><span class="special">-&gt;</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_case3</span> <span class="special">)</span> <span class="special">);</span>
 378   <span class="identifier">ts2</span><span class="special">-&gt;</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_case4</span> <span class="special">)</span> <span class="special">);</span>
 379
 380   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">ts1</span> <span class="special">);</span>
 381   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span><span class="identifier">add</span><span class="special">(</span> <span class="identifier">ts2</span> <span class="special">);</span>
 382
 383   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 384 <span class="special">}</span>
 385 </pre>
 386                 </td></tr></tbody>
 387 </table></div>
 388 <div class="informaltable"><table class="table">
 389 <colgroup><col></colgroup>
 390 <thead><tr><th>
 391                   <p>
 392                     Output
 393                   </p>
 394                 </th></tr></thead>
 395 <tbody><tr><td>
 396 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</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>
 397 <span class="identifier">Running</span> <span class="number">4</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 398 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"Master Test Suite"</span>
 399 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite1"</span>
 400 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case1"</span>
 401 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case1"</span>
 402 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case2"</span>
 403 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case2"</span>
 404 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite1"</span>
 405 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite2"</span>
 406 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case3"</span>
 407 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case3"</span>
 408 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case4"</span>
 409 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case4"</span>
 410 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite2"</span>
 411 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"Master Test Suite"</span>
 412
 413 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 414 </pre>
 415                 </td></tr></tbody>
 416 </table></div>
 417 </div>
 418 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 419 <td align="left"></td>
 420 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 421       contributors<p>
 422         Distributed under the Boost Software License, Version 1.0. (See accompanying
 423         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>)
 424       </p>
 425 </div></td>
 426 </tr></table>
 427 <hr>
 428 <div class="spirit-nav">
 429 <a accesskey="p" href="../test_tree.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="master_test_suite.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 430 </div>
 431 </body>
 432 </html>