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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Adding semantic to a test</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="enabling.html" title="Enabling or disabling test unit execution">
  10 <link rel="next" href="summary_of_the_api_for_declaring.html" title="Summary of the API for declaring and organizing tests">
  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="enabling.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="summary_of_the_api_for_declaring.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.semantic"></a><a class="link" href="semantic.html" title="Adding semantic to a test">Adding semantic
  28       to a test</a>
  29 </h3></div></div></div>
  30 <p>
  31         It is sometimes useful to add a <span class="emphasis"><em>semantic description</em></span>
  32         to a test unit, which may be consulted by the user during a dry run. The
  33         user may then choose the test he/she wants to run based on this information,
  34         instead of basing his/her choice on the test unit <span class="emphasis"><em>name</em></span>,
  35         or instead of looking at the code.
  36       </p>
  37 <p>
  38         The <span class="emphasis"><em>Unit Test Framework</em></span> provides the decorator <a class="link" href="../utf_reference/test_org_reference/decorator_description.html" title="description (decorator)"><code class="computeroutput"><span class="identifier">description</span></code></a> for that purpose.
  39       </p>
  40 <p>
  41         Decorator <code class="computeroutput"><span class="identifier">description</span></code> attaches
  42         an arbitrary string to the test unit. All strings attached to test units
  43         can be displayed when running a test program with parameter <a class="link" href="../utf_reference/rt_param_reference/list_content.html" title="list_content"><code class="computeroutput"><span class="identifier">list_content</span></code></a>. This can be used for
  44         conveying information from the person who composes the test tree to the person
  45         who will be running the test program. Applying more than one decorator <code class="computeroutput"><span class="identifier">description</span></code> to the same test unit means
  46         that the two (or more) strings will be concatenated.
  47       </p>
  48 <h6>
  49 <a name="boost_test.tests_organization.semantic.h0"></a>
  50         <span class="phrase"><a name="boost_test.tests_organization.semantic.example_descr"></a></span><a class="link" href="semantic.html#boost_test.tests_organization.semantic.example_descr">Example: decorator
  51         description</a>
  52       </h6>
  53 <div class="informaltable"><table class="table">
  54 <colgroup><col></colgroup>
  55 <thead><tr><th>
  56                 <p>
  57                   Code
  58                 </p>
  59               </th></tr></thead>
  60 <tbody><tr><td>
  61 <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_09</span>
  62 <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>
  63 <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>
  64
  65 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_1</span><span class="special">,</span>
  66   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">disabled</span><span class="special">()</span>
  67   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"enable only when ODBC is available"</span><span class="special">))</span>
  68 <span class="special">{</span>
  69   <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>
  70 <span class="special">}</span>
  71
  72 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_2</span><span class="special">,</span>
  73   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"descriptions "</span><span class="special">)</span>
  74   <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"add up"</span><span class="special">))</span>
  75 <span class="special">{</span>
  76   <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">2</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span>
  77 <span class="special">}</span>
  78 </pre>
  79               </td></tr></tbody>
  80 </table></div>
  81 <div class="informaltable"><table class="table">
  82 <colgroup><col></colgroup>
  83 <thead><tr><th>
  84                 <p>
  85                   Output
  86                 </p>
  87               </th></tr></thead>
  88 <tbody><tr><td>
  89 <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_09</span> <span class="special">--</span><span class="identifier">list_content</span>
  90 <span class="identifier">test_1</span> <span class="special">:</span> <span class="identifier">enable</span> <span class="identifier">only</span> <span class="identifier">when</span> <span class="identifier">ODBC</span> <span class="identifier">is</span> <span class="identifier">available</span>
  91 <span class="identifier">test_2</span><span class="special">*:</span> <span class="identifier">descriptions</span> <span class="identifier">add</span> <span class="identifier">up</span>
  92 </pre>
  93               </td></tr></tbody>
  94 </table></div>
  95 </div>
  96 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  97 <td align="left"></td>
  98 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
  99       contributors<p>
 100         Distributed under the Boost Software License, Version 1.0. (See accompanying
 101         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>)
 102       </p>
 103 </div></td>
 104 </tr></table>
 105 <hr>
 106 <div class="spirit-nav">
 107 <a accesskey="p" href="enabling.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="summary_of_the_api_for_declaring.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 108 </div>
 109 </body>
 110 </html>