1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 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">></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">></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">></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 © 2001-2020 Boost.Test contributors<p> 146 Distributed under the Boost Software License, Version 1.0. (See accompanying 147 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>) 148 </p> 149</div></td> 150</tr></table> 151<hr> 152<div class="spirit-nav"> 153<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> 154</div> 155</body> 156</html> 157
