libs/test/doc/html/boost_test/tests_organization/decorators/suite_level_decorators.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Suite-level decorators</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="../decorators.html" title="Decorators">
   9 <link rel="prev" href="../decorators.html" title="Decorators">
  10 <link rel="next" href="explicit_decorator_declaration.html" title="Explicit decorator declaration">
  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="../decorators.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../decorators.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="explicit_decorator_declaration.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.decorators.suite_level_decorators"></a><a class="link" href="suite_level_decorators.html" title="Suite-level decorators">Suite-level
  28         decorators</a>
  29 </h4></div></div></div>
  30 <p>
  31           Similarly to test case it is possible to apply list of decorators to test
  32           suite. It is done by specifying a list of decorators as the second argument
  33           to 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> or the third
  34           argument to the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_suite_fixture.html" title="BOOST_FIXTURE_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_SUITE</span></code></a>.
  35         </p>
  36 <h6>
  37 <a name="boost_test.tests_organization.decorators.suite_level_decorators.h0"></a>
  38           <span class="phrase"><a name="boost_test.tests_organization.decorators.suite_level_decorators.example_descr"></a></span><a class="link" href="suite_level_decorators.html#boost_test.tests_organization.decorators.suite_level_decorators.example_descr">Example:
  39           Test suite decorators</a>
  40         </h6>
  41 <div class="informaltable"><table class="table">
  42 <colgroup><col></colgroup>
  43 <thead><tr><th>
  44                   <p>
  45                     Code
  46                   </p>
  47                 </th></tr></thead>
  48 <tbody><tr><td>
  49 <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_02</span>
  50 <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>
  51 <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>
  52
  53 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite1</span><span class="special">,</span> <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">"trivial"</span><span class="special">))</span>
  54
  55   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case1</span><span class="special">)</span>
  56   <span class="special">{</span>
  57     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
  58   <span class="special">}</span>
  59
  60   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case2</span><span class="special">)</span>
  61   <span class="special">{</span>
  62     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
  63   <span class="special">}</span>
  64
  65 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
  66 </pre>
  67                 </td></tr></tbody>
  68 </table></div>
  69 <div class="informaltable"><table class="table">
  70 <colgroup><col></colgroup>
  71 <thead><tr><th>
  72                   <p>
  73                     Output
  74                   </p>
  75                 </th></tr></thead>
  76 <tbody><tr><td>
  77 <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_02</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">trivial</span>
  78 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
  79
  80 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
  81 </pre>
  82                 </td></tr></tbody>
  83 </table></div>
  84 <p>
  85           How a test suite decorator affects the processing of the test units inside
  86           of it varies with the decorator and is described for each decorator in
  87           subsequent sections. For instance, the function of the decorator in the
  88           above example is that when tests are filtered by label <code class="computeroutput"><span class="string">"trivial"</span></code>,
  89           every test unit in suite <code class="computeroutput"><span class="identifier">suite1</span></code>
  90           will be run.
  91         </p>
  92 <p>
  93           Similar to C++ namespace test suite can be closed and reopened within the
  94           same test file or span more than one file and you are allowed to apply
  95           different decorators in each point, where test suite is opened. If this
  96           is the case, the list of decorators applied to the test suite is the union
  97           of decorators specified in each place. Here an example.
  98         </p>
  99 <h6>
 100 <a name="boost_test.tests_organization.decorators.suite_level_decorators.h1"></a>
 101           <span class="phrase"><a name="boost_test.tests_organization.decorators.suite_level_decorators.example_descr0"></a></span><a class="link" href="suite_level_decorators.html#boost_test.tests_organization.decorators.suite_level_decorators.example_descr0">Example:
 102           Decorators on multiple suite openings</a>
 103         </h6>
 104 <div class="informaltable"><table class="table">
 105 <colgroup><col></colgroup>
 106 <thead><tr><th>
 107                   <p>
 108                     Code
 109                   </p>
 110                 </th></tr></thead>
 111 <tbody><tr><td>
 112 <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_03</span>
 113 <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>
 114 <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>
 115
 116 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite1</span><span class="special">,</span> <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">"trivial"</span><span class="special">))</span>
 117
 118   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case1</span><span class="special">)</span>
 119   <span class="special">{</span>
 120     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 121   <span class="special">}</span>
 122
 123 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 124
 125 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite1</span><span class="special">,</span> <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">"simple"</span><span class="special">))</span>
 126
 127   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case2</span><span class="special">)</span>
 128   <span class="special">{</span>
 129     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 130   <span class="special">}</span>
 131
 132 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 133
 134 <span class="identifier">BOOST_AUTO_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite1</span><span class="special">)</span>
 135
 136   <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case3</span><span class="special">)</span>
 137   <span class="special">{</span>
 138     <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
 139   <span class="special">}</span>
 140
 141 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
 142 </pre>
 143                 </td></tr></tbody>
 144 </table></div>
 145 <div class="informaltable"><table class="table">
 146 <colgroup><col></colgroup>
 147 <thead><tr><th>
 148                   <p>
 149                     Output
 150                   </p>
 151                 </th></tr></thead>
 152 <tbody><tr><td>
 153 <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_03</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">trivial</span>
 154 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 155
 156 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 157
 158
 159 <span class="special">&gt;</span> <span class="identifier">decorator_03</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">simple</span>
 160 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 161
 162 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 163 </pre>
 164                 </td></tr></tbody>
 165 </table></div>
 166 <p>
 167           In the above example, the scope of test suite <code class="computeroutput"><span class="identifier">suite1</span></code>
 168           is opened three times. This results in a test suite containing three test
 169           cases and associated with two <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> decorators. Therefore running
 170           tests by label <code class="computeroutput"><span class="string">"trivial"</span></code>
 171           as well as by label <code class="computeroutput"><span class="string">"simple"</span></code>
 172           both result in executing all three test cases from the suite.
 173         </p>
 174 <div class="caution"><table border="0" summary="Caution">
 175 <tr>
 176 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
 177 <th align="left">Caution</th>
 178 </tr>
 179 <tr><td align="left" valign="top"><p>
 180             The above syntax for decorators requires that the compiler supports variadic
 181             macros (added in C++11). If you intend for your test program to also
 182             work for compilers without variadic macros, use explicit decorator syntax,
 183             described below.
 184           </p></td></tr>
 185 </table></div>
 186 </div>
 187 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 188 <td align="left"></td>
 189 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 190       contributors<p>
 191         Distributed under the Boost Software License, Version 1.0. (See accompanying
 192         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>)
 193       </p>
 194 </div></td>
 195 </tr></table>
 196 <hr>
 197 <div class="spirit-nav">
 198 <a accesskey="p" href="../decorators.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../decorators.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="explicit_decorator_declaration.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 199 </div>
 200 </body>
 201 </html>