libs/test/doc/html/boost_test/tests_organization/fixtures/models.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Fixture models</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="../fixtures.html" title="Fixtures">
   9 <link rel="prev" href="../fixtures.html" title="Fixtures">
  10 <link rel="next" href="case.html" title="Test case fixture">
  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="../fixtures.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fixtures.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="case.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.fixtures.models"></a><a class="link" href="models.html" title="Fixture models">Fixture
  28         models</a>
  29 </h4></div></div></div>
  30 <p>
  31           Several fixture interfaces are supported by the <span class="emphasis"><em>Unit Test Framework</em></span>.
  32           The choice of the interface depends mainly on the usage of the fixture.
  33         </p>
  34 <h4>
  35 <a name="boost_test.tests_organization.fixtures.models.h0"></a>
  36           <span class="phrase"><a name="boost_test.tests_organization.fixtures.models.fixture_class_model"></a></span><a class="link" href="models.html#boost_test.tests_organization.fixtures.models.fixture_class_model">Fixture
  37           class model</a>
  38         </h4>
  39 <p>
  40           The <span class="emphasis"><em>Unit Test Framework</em></span> defines the generic fixture
  41           class model as follows:
  42         </p>
  43 <pre class="programlisting"><span class="keyword">struct</span> <span class="special">&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;{</span>
  44   <span class="special">&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;();</span>      <span class="comment">// setup function</span>
  45   <span class="special">~&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;();</span>     <span class="comment">// teardown function</span>
  46 <span class="special">};</span>
  47 </pre>
  48 <p>
  49           In other words a fixture is expected to be implemented as a class where
  50           the class constructor serves as a <code class="computeroutput"><span class="identifier">setup</span></code>
  51           method and class destructor serves as <code class="computeroutput"><span class="identifier">teardown</span></code>
  52           method.
  53         </p>
  54 <p>
  55           The class model above has some limitations though:
  56         </p>
  57 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  58 <li class="listitem">
  59               it is not possible to have exceptions in the teardown function, especially
  60               any test assertions that aborts the current test case is not possible
  61               (as those use exceptions)
  62             </li>
  63 <li class="listitem">
  64               it is sometimes more natural to use the constructor/destructor to perform
  65               the necessary resource allocation/release of the fixture, and that
  66               will be consumed in the test cases, and check for the proper state
  67               of the fixture in separate functions. Those checks are the pre-conditions
  68               for the test case to run, and the post-conditions that should be met
  69               after the test case has been running.
  70             </li>
  71 </ul></div>
  72 <p>
  73           This is why the <span class="emphasis"><em>Unit Test Framework</em></span> also supports
  74           (Boost 1.65 on) optional <code class="computeroutput"><span class="identifier">setup</span></code>
  75           and/or <code class="computeroutput"><span class="identifier">teardown</span></code> functions
  76           as follow:
  77         </p>
  78 <pre class="programlisting"><span class="keyword">struct</span> <span class="special">&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;{</span>
  79   <span class="special">&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;();</span>      <span class="comment">// ctor</span>
  80   <span class="special">~&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;();</span>     <span class="comment">// dtor</span>
  81   <span class="keyword">void</span> <span class="identifier">setup</span><span class="special">();</span>          <span class="comment">// setup, optional</span>
  82   <span class="keyword">void</span> <span class="identifier">teardown</span><span class="special">();</span>       <span class="comment">// teardown, optional</span>
  83 <span class="special">};</span>
  84 </pre>
  85 <div class="note"><table border="0" summary="Note">
  86 <tr>
  87 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
  88 <th align="left">Note</th>
  89 </tr>
  90 <tr><td align="left" valign="top"><p>
  91             As mentioned, the declaration/implementation of the <code class="computeroutput"><span class="identifier">setup</span></code>
  92             and <code class="computeroutput"><span class="identifier">teardown</span></code> are optional:
  93             the <span class="emphasis"><em>Unit Test Framework</em></span> will check the existence
  94             of those and will call them adequately. However in C++98, it is not possible
  95             to detect those declaration in case those are inherited (it works fine
  96             for compiler supporting <code class="computeroutput"><span class="keyword">auto</span></code>
  97             and <code class="computeroutput"><span class="keyword">decltype</span></code>).
  98           </p></td></tr>
  99 </table></div>
 100 <p>
 101           This model is expected from fixtures used with <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_case_fixture.html" title="BOOST_FIXTURE_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span></code></a> and <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>.
 102         </p>
 103 <h4>
 104 <a name="boost_test.tests_organization.fixtures.models.h1"></a>
 105           <span class="phrase"><a name="boost_test.tests_organization.fixtures.models.flexible_models"></a></span><a class="link" href="models.html#boost_test.tests_organization.fixtures.models.flexible_models">Flexible
 106           models</a>
 107         </h4>
 108 <p>
 109           In addition to <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_test_case_fixture.html" title="BOOST_FIXTURE_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span></code></a> and <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> the
 110           <span class="emphasis"><em>Unit Test Framework</em></span> allows to associate fixture with
 111           test unit using the decorator <a class="link" href="../../utf_reference/test_org_reference/decorator_fixture.html" title="fixture (decorator)"><code class="computeroutput"><span class="identifier">fixture</span></code></a>. This decorator supports
 112           additional models for declaring the <code class="computeroutput"><span class="identifier">setup</span></code>
 113           and <code class="computeroutput"><span class="identifier">teardown</span></code>:
 114         </p>
 115 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 116 <li class="listitem">
 117               a fixture defined according to the fixture class model above
 118             </li>
 119 <li class="listitem">
 120 <p class="simpara">
 121               a fixture defined according to the extended fixture class model, which
 122               allows for the fixture constructor to takes one argument. For example:
 123             </p>
 124 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Fx</span>
 125 <span class="special">{</span>
 126   <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s</span><span class="special">;</span>
 127   <span class="identifier">Fx</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">s_</span> <span class="special">=</span> <span class="string">""</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">s</span><span class="special">(</span><span class="identifier">s_</span><span class="special">)</span>
 128       <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"ctor "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">);</span> <span class="special">}</span>
 129   <span class="keyword">void</span> <span class="identifier">setup</span><span class="special">()</span>
 130       <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"optional setup "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">);</span> <span class="special">}</span>
 131   <span class="keyword">void</span> <span class="identifier">teardown</span><span class="special">()</span>
 132       <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"optional teardown "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">);</span> <span class="special">}</span>
 133   <span class="special">~</span><span class="identifier">Fx</span><span class="special">()</span>
 134       <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"dtor "</span> <span class="special">&lt;&lt;</span> <span class="identifier">s</span><span class="special">);</span> <span class="special">}</span>
 135 <span class="special">};</span>
 136 </pre>
 137 </li>
 138 <li class="listitem">
 139 <p class="simpara">
 140               a fixture defined as a pair of free functions for the <code class="computeroutput"><span class="identifier">setup</span></code> and <code class="computeroutput"><span class="identifier">teardown</span></code>
 141               (latter optional)
 142             </p>
 143 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">setup</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"set up"</span><span class="special">);</span> <span class="special">}</span>
 144 <span class="keyword">void</span> <span class="identifier">teardown</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"tear down"</span><span class="special">);</span> <span class="special">}</span>
 145 </pre>
 146 </li>
 147 </ul></div>
 148 <p>
 149           For complete example of test module which uses these models please check
 150           decorator <a class="link" href="../../utf_reference/test_org_reference/decorator_fixture.html" title="fixture (decorator)"><code class="computeroutput"><span class="identifier">fixture</span></code></a>.
 151         </p>
 152 </div>
 153 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 154 <td align="left"></td>
 155 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 156       contributors<p>
 157         Distributed under the Boost Software License, Version 1.0. (See accompanying
 158         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>)
 159       </p>
 160 </div></td>
 161 </tr></table>
 162 <hr>
 163 <div class="spirit-nav">
 164 <a accesskey="p" href="../fixtures.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fixtures.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="case.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 165 </div>
 166 </body>
 167 </html>