devn00b
/
EQ2EMu


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Test suite</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Boost.Test">
<link rel="up" href="../test_tree.html" title="Test tree">
<link rel="prev" href="../test_tree.html" title="Test tree">
<link rel="next" href="master_test_suite.html" title="Master test suite">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_test.tests_organization.test_tree.test_suite"></a><a class="link" href="test_suite.html" title="Test suite">Test
        suite</a>
</h4></div></div></div>
<p>
          If you consider test cases as leaves on the test tree, the test suite can
          be considered as branch and the <span class="emphasis"><em>master test suite</em></span>
          as the <span class="emphasis"><em>root</em></span>. Unlike real trees though, our tree in
          many cases consists only of leaves attached directly to the root. This
          is common for all test cases to reside directly in the master test suite.
          If you do want to construct a hierarchical test suite structure the <span class="emphasis"><em>Unit
          Test Framework</em></span> provides both manual and automated test suite
          creation and registration facilities:
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              Test suite with automated registration
            </li>
<li class="listitem">
              Manually registered test suite
            </li>
</ol></div>
<p>
          In addition the <span class="emphasis"><em>Unit Test Framework</em></span> presents a notion
          of the <a class="link" href="master_test_suite.html" title="Master test suite">Master
          test suite</a>. The most important reason to learn about this component
          is that it provides an ability to access command line arguments supplied
          to a test module.
        </p>
<a name="ref_BOOST_AUTO_TEST_SUITE"></a><h4>
<a name="boost_test.tests_organization.test_tree.test_suite.h0"></a>
          <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
          registration</a>
        </h4>
<p>
          The solution the <span class="emphasis"><em>Unit Test Framework</em></span> presents for
          automated test suite creation and registration is designed to facilitate
          multiple points of definition, arbitrary test suites depth and smooth integration
          with automated test case creation and registration. This facility should
          significantly simplify a test tree construction process in comparison with
          manual explicit registration case.
        </p>
<p>
          The implementation is based on the order of file scope variables definitions
          within a single compilation unit. The semantic of this facility is very
          similar to the namespace feature of C++, including support for test suite
          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
          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
          same test suite can be restarted multiple times inside the same test file
          or in a different test files. In a result all test units will be part of
          the same test suite in a constructed test tree.
        </p>
<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>
<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">();</span>
</pre>
<p>
          Test units defined in between test suite start and end declarations become
          members of the test suite. A test unit always becomes the member of the
          closest test suite declared. Test units declared at a test file scope become
          members of the master test suite. There is no limit on depth of test suite
          inclusion.
        </p>
<p>
          This example creates a test tree that matches exactly the one created in
          the manual test suite registration example.
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.test_suite.h1"></a>
          <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:
          Test suites with automated registration</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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>
<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>

<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite1</span> <span class="special">)</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case1</span> <span class="special">)</span>
<span class="special">{</span>
  <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>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case2</span> <span class="special">)</span>
<span class="special">{</span>
  <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>
  <span class="identifier">BOOST_FAIL</span><span class="special">(</span> <span class="string">"Should never reach this line"</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite2</span> <span class="special">)</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case3</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case4</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">false</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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="identifier">Running</span> <span class="number">4</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
<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>
<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>

<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>
</pre>
                </td></tr></tbody>
</table></div>
<p>
          As you can see test tree construction in this example is more straightforward
          and automated.
        </p>
<p>
          In the example below, the test suite <code class="computeroutput"><span class="identifier">test_suite</span></code>
          consists of two parts. Their definition is remote and is separated by another
          test case. In fact these parts may even reside in different test files.
          The resulting test tree remains the same. As you can see from the output
          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
          <code class="computeroutput"><span class="identifier">test_suite</span></code>.
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.test_suite.h2"></a>
          <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:
          Test suite extension using automated registration facility</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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>
<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>

<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite</span> <span class="special">)</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case1</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_ERROR</span><span class="special">(</span> <span class="string">"some error 1"</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>


<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>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span> <span class="identifier">test_suite</span> <span class="special">)</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case2</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">BOOST_ERROR</span><span class="special">(</span> <span class="string">"some error 2"</span> <span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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>
<span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
<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>
<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>

<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>
  <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>
  <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>
  <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>
  <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>

  <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>
    <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>
    <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>

    <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>
      <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>

    <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>
      <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>

  <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>
    <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>
</pre>
                </td></tr></tbody>
</table></div>
<h4>
<a name="boost_test.tests_organization.test_tree.test_suite.h3"></a>
          <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
          suites with manual registration</a>
        </h4>
<p>
          To create a test suite manually you need to
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              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>
              class,
            </li>
<li class="listitem">
              register it in test tree, and
            </li>
<li class="listitem">
              populate it with test cases (or lower level test suites).
            </li>
</ol></div>
<a name="ref_test_case_registration"></a><h5>
<a name="boost_test.tests_organization.test_tree.test_suite.h4"></a>
          <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
          unit registration interface</a>
        </h5>
<p>
          The <span class="emphasis"><em>Unit Test Framework</em></span> models the notion of test
          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>.
          For complete class interface reference check advanced section of this documentation.
          Here you should only be interested in a single test unit registration interface:
        </p>
<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>
</pre>
<p>
          The first parameter is a pointer to a newly created test unit. The second
          optional parameter - expected_failures - defines the number of test assertions
          that are expected to fail within the test unit. By default no errors are
          expected.
        </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
            Be careful when supplying a number of expected failures for test suites.
            By default the <span class="emphasis"><em>Unit Test Framework</em></span> calculates the
            number of expected failures in test suite as the sum of appropriate values
            in all test units that constitute it. And it rarely makes sense to change
            this.
          </p></td></tr>
</table></div>
<p>
          The third optional parameter - <code class="computeroutput"><span class="identifier">timeout</span></code>
          - defines the timeout value for the test unit. As of now the <span class="emphasis"><em>Unit
          Test Framework</em></span> isn't able to set a timeout for the test suite
          execution, so this parameter makes sense only for test case registration.
          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>
          for more details about the timeout value.
        </p>
<p>
          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
          another <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html#idm46279112866240-bb">add</a></code> interface covered in
          the advanced section of this documentation.
        </p>
<a name="ref_BOOST_TEST_SUITE"></a><h5>
<a name="boost_test.tests_organization.test_tree.test_suite.h5"></a>
          <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
          suite instance construction</a>
        </h5>
<p>
          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
          implementation details and you only required to specify the test suite
          name:
        </p>
<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>
</pre>
<p>
          <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
          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
          constructed instance. Alternatively you can create an instance of 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> yourself.
        </p>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
            <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
            on the heap and the compiler won't allow you to create one on the stack.
          </p></td></tr>
</table></div>
<p>
          Newly created test suite has to be registered in a parent one using the
          <code class="computeroutput"><span class="identifier">add</span></code> interface. Both test
          suite creation and registration is performed in the test module initialization
          function.
        </p>
<p>
          The example below creates a test tree, which can be represented by the
          following hierarchy:
        </p>
<p>
          <span class="inlinemediaobject"><img src="../../../images/class-hier.jpg"></span>
        </p>
<h6>
<a name="boost_test.tests_organization.test_tree.test_suite.h6"></a>
          <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:
          Manually registered test suites</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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>
<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>

<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>
<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>
<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>
<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>

<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>
<span class="special">{</span>
  <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>
  <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>
  <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>

  <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>
  <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>
  <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>

  <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>
  <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>

  <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<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>
<span class="identifier">Running</span> <span class="number">4</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"Master Test Suite"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite1"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case1"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case1"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case2"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case2"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite1"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite2"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case3"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case3"</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case4"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_case4"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"test_suite2"</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"Master Test Suite"</span>

<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
</pre>
                </td></tr></tbody>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
      contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        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>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>