libs/test/doc/html/boost_test/tests_organization/test_cases/test_organization_nullary.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Test cases without parameters</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_cases.html" title="Test cases">
   9 <link rel="prev" href="../test_cases.html" title="Test cases">
  10 <link rel="next" href="test_case_generation.html" title="Data-driven test cases">
  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="../test_cases.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_cases.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_case_generation.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_cases.test_organization_nullary"></a><a class="link" href="test_organization_nullary.html" title="Test cases without parameters">Test
  28         cases without parameters</a>
  29 </h4></div></div></div>
  30 <p>
  31           The most common scenario is that you want to write test case without any
  32           parameters. The <span class="emphasis"><em>Unit Test Framework</em></span> provides you with
  33           both automatic and manual registration APIs to declare such test case.
  34         </p>
  35 <a name="ref_BOOST_AUTO_TEST_CASE"></a><h5>
  36 <a name="boost_test.tests_organization.test_cases.test_organization_nullary.h0"></a>
  37           <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_organization_nullary.automated_registration"></a></span><a class="link" href="test_organization_nullary.html#boost_test.tests_organization.test_cases.test_organization_nullary.automated_registration">Automated
  38           registration</a>
  39         </h5>
  40 <p>
  41           To declare a test case without parameters, which is registered in place
  42           of implementation, employ the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a>.
  43         </p>
  44 <pre class="programlisting"><a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">);</span>
  45 </pre>
  46 <p>
  47           This API is designed to closely mimic nullary free function declaration
  48           syntax. In comparison with free function all you need to do is to skip
  49           result type and brackets and wrap test case name into BOOST_AUTO_TEST_CASE:
  50         </p>
  51 <h6>
  52 <a name="boost_test.tests_organization.test_cases.test_organization_nullary.h1"></a>
  53           <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_organization_nullary.example_descr"></a></span><a class="link" href="test_organization_nullary.html#boost_test.tests_organization.test_cases.test_organization_nullary.example_descr">Example:
  54           Nullary function based test case with automated registration</a>
  55         </h6>
  56 <div class="informaltable"><table class="table">
  57 <colgroup><col></colgroup>
  58 <thead><tr><th>
  59                   <p>
  60                     Code
  61                   </p>
  62                 </th></tr></thead>
  63 <tbody><tr><td>
  64 <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">example</span>
  65 <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>
  66
  67 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">free_test_function</span> <span class="special">)</span>
  68 <span class="comment">/* Compare with void free_test_function() */</span>
  69 <span class="special">{</span>
  70   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
  71 <span class="special">}</span>
  72 </pre>
  73                 </td></tr></tbody>
  74 </table></div>
  75 <div class="informaltable"><table class="table">
  76 <colgroup><col></colgroup>
  77 <thead><tr><th>
  78                   <p>
  79                     Output
  80                   </p>
  81                 </th></tr></thead>
  82 <tbody><tr><td>
  83 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
  84 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
  85
  86 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
  87 </pre>
  88                 </td></tr></tbody>
  89 </table></div>
  90 <p>
  91           With this macro you don't need to implement any other registration steps.
  92           The macro creates and registers the test case with the name <code class="computeroutput"><span class="identifier">free_test_function</span></code> automatically.
  93         </p>
  94 <a name="ref_BOOST_TEST_CASE"></a><h5>
  95 <a name="boost_test.tests_organization.test_cases.test_organization_nullary.h2"></a>
  96           <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_organization_nullary.manual_registration"></a></span><a class="link" href="test_organization_nullary.html#boost_test.tests_organization.test_cases.test_organization_nullary.manual_registration">Manual
  97           registration</a>
  98         </h5>
  99 <p>
 100           The <span class="emphasis"><em>Unit Test Framework</em></span> allows to manually create
 101           test case without parameters based on nullary free functions, nullary function
 102           objects (including those created with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span></code>
 103           and nullary <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span></code> instances). To do this, employ
 104           the macro <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</span></code></a>:
 105         </p>
 106 <pre class="programlisting"><span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span><span class="identifier">test_function</span><span class="special">);</span>
 107 </pre>
 108 <p>
 109           <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</span></code></a> creates an instance
 110           of the class <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_case.html" title="Class test_case">boost::unit_test::test_case</a></code>
 111           and returns a pointer to the constructed instance. The test case name is
 112           deduced from the macro argument test_function. If you prefer to assign
 113           a different test case name, you have either to
 114         </p>
 115 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 116 <li class="listitem">
 117               use the macro <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> instead
 118             </li>
 119 <li class="listitem">
 120               or use the underlying <code class="computeroutput"><a class="link" href="../../../header/boost/test/tree/test_unit_hpp.html" title="Header &lt;boost/test/tree/test_unit.hpp&gt;">make_test_case</a></code> interface
 121               instead.
 122             </li>
 123 </ul></div>
 124 <p>
 125           To register a new test case, employ the method <code class="computeroutput"><a class="link" href="../../../boost/unit_test/test_suite.html#idm46279112866240-bb">test_suite::add</a></code>. Both test case creation
 126           and registration are performed in the <a class="link" href="../../adv_scenarios/test_module_init_overview.html" title="Test module's initialization">test
 127           module initialization function</a>.
 128         </p>
 129 <p>
 130           Here is the simplest example of manually registered test case. A single
 131           test case is created and registered inside the test module initialization
 132           routine. Note that the free function name is passed by address to the macro
 133           <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</span></code></a>`.
 134         </p>
 135 <a name="ref_bt_example01"></a><h6>
 136 <a name="boost_test.tests_organization.test_cases.test_organization_nullary.h3"></a>
 137           <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_organization_nullary.example_descr0"></a></span><a class="link" href="test_organization_nullary.html#boost_test.tests_organization.test_cases.test_organization_nullary.example_descr0">Example:
 138           Nullary free function manually registered</a>
 139         </h6>
 140 <div class="informaltable"><table class="table">
 141 <colgroup><col></colgroup>
 142 <thead><tr><th>
 143                   <p>
 144                     Code
 145                   </p>
 146                 </th></tr></thead>
 147 <tbody><tr><td>
 148 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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>
 149 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 150
 151 <span class="keyword">void</span> <span class="identifier">free_test_function</span><span class="special">()</span>
 152 <span class="special">{</span>
 153   <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
 154 <span class="special">}</span>
 155
 156 <span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span>
 157 <span class="special">{</span>
 158   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 159     <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">free_test_function</span> <span class="special">)</span> <span class="special">);</span>
 160   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 161     <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE_NAME</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">free_test_function</span><span class="special">,</span> <span class="string">"second-check-free-test-function"</span> <span class="special">)</span> <span class="special">);</span>
 162   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 163 <span class="special">}</span>
 164 </pre>
 165                 </td></tr></tbody>
 166 </table></div>
 167 <div class="informaltable"><table class="table">
 168 <colgroup><col></colgroup>
 169 <thead><tr><th>
 170                   <p>
 171                     Output
 172                   </p>
 173                 </th></tr></thead>
 174 <tbody><tr><td>
 175 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">unit_scope</span>
 176 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 177 <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span>
 178 <span class="identifier">example</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">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span>
 179 <span class="identifier">example</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">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"free_test_function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">50u</span><span class="identifier">s</span>
 180 <span class="identifier">example</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"second-check-free-test-function"</span>
 181 <span class="identifier">example</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"second-check-free-test-function"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">32u</span><span class="identifier">s</span>
 182 <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"Master Test Suite"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">158u</span><span class="identifier">s</span>
 183
 184 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
 185 </pre>
 186                 </td></tr></tbody>
 187 </table></div>
 188 <p>
 189           A test case can be implemented as a method of a class. In this case a pointer
 190           to the class instance has to be bound to the test method to create a test
 191           case. You can use the same instance of the class for multiple test cases.
 192           The <span class="emphasis"><em>Unit Test Framework</em></span> doesn't take an ownership
 193           of the class instance and you are required to manage the class instance
 194           lifetime yourself.
 195         </p>
 196 <div class="warning"><table border="0" summary="Warning">
 197 <tr>
 198 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
 199 <th align="left">Warning</th>
 200 </tr>
 201 <tr><td align="left" valign="top"><p>
 202             The class instance can't be defined in the initialization function scope,
 203             since it becomes invalid as soon as the test execution exits it. It needs
 204             to be either defined statically/globally or managed using a shared pointer.
 205           </p></td></tr>
 206 </table></div>
 207 <h6>
 208 <a name="boost_test.tests_organization.test_cases.test_organization_nullary.h4"></a>
 209           <span class="phrase"><a name="boost_test.tests_organization.test_cases.test_organization_nullary.example_descr1"></a></span><a class="link" href="test_organization_nullary.html#boost_test.tests_organization.test_cases.test_organization_nullary.example_descr1">Example:
 210           Nullary method of a class bound to shared class instance and manually registered</a>
 211         </h6>
 212 <div class="informaltable"><table class="table">
 213 <colgroup><col></colgroup>
 214 <thead><tr><th>
 215                   <p>
 216                     Code
 217                   </p>
 218                 </th></tr></thead>
 219 <tbody><tr><td>
 220 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><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>
 221 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">bind</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 222 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>
 223
 224 <span class="keyword">class</span> <span class="identifier">test_class</span>
 225 <span class="special">{</span>
 226 <span class="keyword">public</span><span class="special">:</span>
 227   <span class="keyword">void</span> <span class="identifier">test_method1</span><span class="special">()</span>
 228   <span class="special">{</span>
 229     <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
 230   <span class="special">}</span>
 231   <span class="keyword">void</span> <span class="identifier">test_method2</span><span class="special">()</span>
 232   <span class="special">{</span>
 233     <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">false</span> <span class="comment">/* test assertion */</span> <span class="special">);</span>
 234   <span class="special">}</span>
 235 <span class="special">};</span>
 236
 237 <span class="identifier">test_suite</span><span class="special">*</span> <span class="identifier">init_unit_test_suite</span><span class="special">(</span> <span class="keyword">int</span> <span class="comment">/*argc*/</span><span class="special">,</span> <span class="keyword">char</span><span class="special">*</span> <span class="comment">/*argv*/</span><span class="special">[]</span> <span class="special">)</span>
 238 <span class="special">{</span>
 239   <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span><span class="identifier">test_class</span><span class="special">&gt;</span> <span class="identifier">tester</span><span class="special">(</span> <span class="keyword">new</span> <span class="identifier">test_class</span> <span class="special">);</span>
 240
 241   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 242     <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_class</span><span class="special">::</span><span class="identifier">test_method1</span><span class="special">,</span> <span class="identifier">tester</span> <span class="special">)));</span>
 243   <span class="identifier">framework</span><span class="special">::</span><span class="identifier">master_test_suite</span><span class="special">().</span>
 244     <span class="identifier">add</span><span class="special">(</span> <span class="identifier">BOOST_TEST_CASE</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">test_class</span><span class="special">::</span><span class="identifier">test_method2</span><span class="special">,</span> <span class="identifier">tester</span> <span class="special">)));</span>
 245   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 246 <span class="special">}</span>
 247 </pre>
 248                 </td></tr></tbody>
 249 </table></div>
 250 <div class="informaltable"><table class="table">
 251 <colgroup><col></colgroup>
 252 <thead><tr><th>
 253                   <p>
 254                     Output
 255                   </p>
 256                 </th></tr></thead>
 257 <tbody><tr><td>
 258 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">example</span>
 259 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
 260 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">22</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"boost::bind( &amp;test_class::test_method2, tester )"</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>
 261
 262 <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">"Master Test Suite"</span>
 263 </pre>
 264                 </td></tr></tbody>
 265 </table></div>
 266 </div>
 267 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 268 <td align="left"></td>
 269 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 270       contributors<p>
 271         Distributed under the Boost Software License, Version 1.0. (See accompanying
 272         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>)
 273       </p>
 274 </div></td>
 275 </tr></table>
 276 <hr>
 277 <div class="spirit-nav">
 278 <a accesskey="p" href="../test_cases.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_cases.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_case_generation.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 279 </div>
 280 </body>
 281 </html>