libs/test/doc/html/boost_test/tests_organization/test_tree/test_naming.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Tests naming</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="../test_tree.html" title="Test tree">
   9 <link rel="prev" href="master_test_suite.html" title="Master test suite">
  10 <link rel="next" href="test_tree_content.html" title="Test tree content">
  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="master_test_suite.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="test_tree_content.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.test_tree.test_naming"></a><a class="link" href="test_naming.html" title="Tests naming">Tests
  28         naming</a>
  29 </h4></div></div></div>
  30 <h3>
  31 <a name="boost_test.tests_organization.test_tree.test_naming.h0"></a>
  32           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_naming.acceptable_characters_for_names"></a></span><a class="link" href="test_naming.html#boost_test.tests_organization.test_tree.test_naming.acceptable_characters_for_names">Acceptable
  33           characters for names</a>
  34         </h3>
  35 <p>
  36           The <span class="emphasis"><em>Unit Test Framework</em></span> is flexible on the naming
  37           the test units (test cases/suites) and it is possible to use a wide variety
  38           of characters. However there are scenarios where the name of a test unit
  39           may collide with other features of the <span class="emphasis"><em>Unit Test Framework</em></span>.
  40           For instance:
  41         </p>
  42 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  43 <li class="listitem">
  44               a character may collide with specific command line filters for selecting
  45               a subset of the test tree. Among those characters: <code class="computeroutput"><span class="char">'@'</span></code>,
  46               <code class="computeroutput"><span class="char">'+'</span></code> or <code class="computeroutput"><span class="char">'/'</span></code>
  47               (see <a class="link" href="../../runtime_config/test_unit_filtering.html" title="Test unit filtering">this
  48               section</a> for more details)
  49             </li>
  50 <li class="listitem">
  51               a name containing a character that is reserved for the shell/terminal,
  52               such as '!', '*' ..., may prevent the test name to be passed on the
  53               command line <span class="bold"><strong>as is</strong></span>.
  54             </li>
  55 </ul></div>
  56 <p>
  57           To prevent any conflicting declaration, the <span class="emphasis"><em>Unit Test Framework</em></span>
  58           <span class="bold"><strong>sanitizes</strong></span> the name given to a test unit
  59           (case or suite), prior to adding the test to the test tree. Any conflicting
  60           character is replaced by an underscore <code class="computeroutput"><span class="char">'_'</span></code>.
  61         </p>
  62 <div class="note"><table border="0" summary="Note">
  63 <tr>
  64 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  65 <th align="left">Note</th>
  66 </tr>
  67 <tr><td align="left" valign="top"><p>
  68             <span class="bold"><strong>Spaces</strong></span> are not considered as <span class="emphasis"><em>special
  69             chars</em></span> and are preserved, except for the leading and trailing
  70             spaces which are removed.
  71           </p></td></tr>
  72 </table></div>
  73 <div class="note"><table border="0" summary="Note">
  74 <tr>
  75 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  76 <th align="left">Note</th>
  77 </tr>
  78 <tr><td align="left" valign="top"><p>
  79             The sanitization of the test unit names has been introduced in <a class="link" href="../../change_log.html#ref_CHANGE_LOG_3_7">Boost 1.67</a>.
  80           </p></td></tr>
  81 </table></div>
  82 <h3>
  83 <a name="boost_test.tests_organization.test_tree.test_naming.h1"></a>
  84           <span class="phrase"><a name="boost_test.tests_organization.test_tree.test_naming.constraints_on_test_names"></a></span><a class="link" href="test_naming.html#boost_test.tests_organization.test_tree.test_naming.constraints_on_test_names">Constraints
  85           on test names</a>
  86         </h3>
  87 <p>
  88           The <span class="emphasis"><em>Unit Test Framework</em></span> considers an error if two
  89           sibling test cases have the same name. This consistency check is performed
  90           at runtime and is not sensitive to test filtering.
  91         </p>
  92 <p>
  93           For test-cases registered automatically, and within the same compilation
  94           unit, a compilation error should be raised by the compiler in case of name
  95           conflict. For manual registration of test cases and in case of conflicts,
  96           the too <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_case.html" title="BOOST_TEST_CASE and BOOST_TEST_CASE_NAME"><code class="computeroutput"><span class="identifier">BOOST_TEST_CASE_NAME</span></code></a> may be used.
  97         </p>
  98 <p>
  99           The data driven tests are automatically created in an isolated test-suite
 100           and with a name that is indexed on the sample.
 101         </p>
 102 <div class="note"><table border="0" summary="Note">
 103 <tr>
 104 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 105 <th align="left">Note</th>
 106 </tr>
 107 <tr><td align="left" valign="top"><p>
 108             This constraints does not apply to test-suites: Opening/closing a test-suite
 109             declaration adds the test-cases to an existing or newly created test-suite
 110             of that name.
 111           </p></td></tr>
 112 </table></div>
 113 </div>
 114 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 115 <td align="left"></td>
 116 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 117       contributors<p>
 118         Distributed under the Boost Software License, Version 1.0. (See accompanying
 119         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>)
 120       </p>
 121 </div></td>
 122 </tr></table>
 123 <hr>
 124 <div class="spirit-nav">
 125 <a accesskey="p" href="master_test_suite.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="test_tree_content.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 126 </div>
 127 </body>
 128 </html>