libs/test/doc/html/boost_test/tests_organization/tests_grouping.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Grouping tests into logical units by labels</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="../tests_organization.html" title="Declaring and organizing tests">
   9 <link rel="prev" href="tests_dependencies.html" title="Managing test dependencies">
  10 <link rel="next" href="enabling.html" title="Enabling or disabling test unit execution">
  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="tests_dependencies.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.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="enabling.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="boost_test.tests_organization.tests_grouping"></a><a class="link" href="tests_grouping.html" title="Grouping tests into logical units by labels">Grouping
  28       tests into logical units by labels</a>
  29 </h3></div></div></div>
  30 <p>
  31         Test-suites and test cases define a hierarchy called the <span class="emphasis"><em>test tree</em></span>,
  32         which is useful for organizing tests. These organization defines an implicit
  33         grouping of test unit following the <span class="emphasis"><em>subtrees</em></span> extracted
  34         from the test tree, by just designing a node on the test tree. Being able
  35         to design a group of tests enable, for instance, to execute this group of
  36         test only (covered in <a class="link" href="../runtime_config/test_unit_filtering.html" title="Test unit filtering">this
  37         section</a>).
  38       </p>
  39 <p>
  40         However, the subtrees might not reflect all the possible grouping of test
  41         units the usage of the test module would require <a href="#ftn.boost_test.tests_organization.tests_grouping.f0" class="footnote" name="boost_test.tests_organization.tests_grouping.f0"><sup class="footnote">[5]</sup></a>.
  42       </p>
  43 <p>
  44         The <span class="emphasis"><em>Unit Test Framework</em></span> provides a flexible way of grouping
  45         test units by the use of <span class="emphasis"><em>labels</em></span>, using the decorator
  46         <a class="link" href="../utf_reference/test_org_reference/decorator_label.html" title="label (decorator)"><code class="computeroutput"><span class="identifier">label</span></code></a>. It is possible to associate
  47         more than one label with a test unit.
  48       </p>
  49 <p>
  50         Labels can be associated to test cases and test suites. For the latter, the
  51         label is inherited by all the nodes in the subtree defined by the labelled
  52         test suite: decorating a test suite with label <code class="computeroutput"><span class="identifier">L</span></code>
  53         is equivalent to decorating every test unit inside with <code class="computeroutput"><span class="identifier">L</span></code>.
  54       </p>
  55 <div class="tip"><table border="0" summary="Tip">
  56 <tr>
  57 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
  58 <th align="left">Tip</th>
  59 </tr>
  60 <tr><td align="left" valign="top"><p>
  61           it is possible to list all labels of a test module from the CLI by using
  62           the <a class="link" href="../utf_reference/rt_param_reference/list_labels.html" title="list_labels"><code class="computeroutput"><span class="special">--</span><span class="identifier">list_labels</span></code></a>
  63           switch
  64         </p></td></tr>
  65 </table></div>
  66 <h6>
  67 <a name="boost_test.tests_organization.tests_grouping.h0"></a>
  68         <span class="phrase"><a name="boost_test.tests_organization.tests_grouping.example_descr"></a></span><a class="link" href="tests_grouping.html#boost_test.tests_organization.tests_grouping.example_descr">Example:
  69         decorator label</a>
  70       </h6>
  71 <div class="informaltable"><table class="table">
  72 <colgroup><col></colgroup>
  73 <thead><tr><th>
  74                 <p>
  75                   Code
  76                 </p>
  77               </th></tr></thead>
  78 <tbody><tr><td>
  79 <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">decorator_04</span>
  80 <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>
  81 <span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
  82
  83 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test1</span><span class="special">,</span>
  84   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"l1"</span><span class="special">))</span>
  85 <span class="special">{</span>
  86   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
  87 <span class="special">}</span>
  88
  89 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test2</span><span class="special">,</span>
  90   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"l1"</span><span class="special">)</span>
  91   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"l2"</span><span class="special">))</span>
  92 <span class="special">{</span>
  93   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
  94 <span class="special">}</span>
  95
  96 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test3</span><span class="special">)</span>
  97 <span class="special">{</span>
  98   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span>
  99 <span class="special">}</span>
 100 </pre>
 101               </td></tr></tbody>
 102 </table></div>
 103 <div class="informaltable"><table class="table">
 104 <colgroup><col></colgroup>
 105 <thead><tr><th>
 106                 <p>
 107                   Output
 108                 </p>
 109               </th></tr></thead>
 110 <tbody><tr><td>
 111 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_04</span>
 112 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 113 <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="special">:</span> <span class="identifier">in</span> <span class="string">"test1"</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>
 114 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test2"</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>
 115 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">20</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test3"</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>
 116
 117 <span class="special">***</span> <span class="number">3</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">"decorator_04"</span>
 118
 119
 120 <span class="special">&gt;</span> <span class="identifier">decorator_04</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">l1</span>
 121 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 122 <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="special">:</span> <span class="identifier">in</span> <span class="string">"test1"</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>
 123 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test2"</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>
 124
 125 <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">"decorator_04"</span>
 126
 127
 128 <span class="special">&gt;</span> <span class="identifier">decorator_04</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">l2</span>
 129 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
 130 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">15</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test2"</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>
 131
 132 <span class="special">***</span> <span class="number">1</span> <span class="identifier">failure</span> <span class="identifier">is</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">"decorator_04"</span>
 133 </pre>
 134               </td></tr></tbody>
 135 </table></div>
 136 <div class="footnotes">
 137 <br><hr style="width:100; text-align:left;margin-left: 0">
 138 <div id="ftn.boost_test.tests_organization.tests_grouping.f0" class="footnote"><p><a href="#boost_test.tests_organization.tests_grouping.f0" class="para"><sup class="para">[5] </sup></a>
 139           For instance, selecting two siblings without the parent node
 140         </p></div>
 141 </div>
 142 </div>
 143 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 144 <td align="left"></td>
 145 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 146       contributors<p>
 147         Distributed under the Boost Software License, Version 1.0. (See accompanying
 148         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>)
 149       </p>
 150 </div></td>
 151 </tr></table>
 152 <hr>
 153 <div class="spirit-nav">
 154 <a accesskey="p" href="tests_dependencies.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.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="enabling.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 155 </div>
 156 </body>
 157 </html>