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

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Fixtures</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="decorators/explicit_decorator_declaration.html" title="Explicit decorator declaration">
  10 <link rel="next" href="fixtures/models.html" title="Fixture models">
  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/explicit_decorator_declaration.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="fixtures/models.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.fixtures"></a><a class="link" href="fixtures.html" title="Fixtures">Fixtures</a>
  28 </h3></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="fixtures/models.html">Fixture
  31         models</a></span></dt>
  32 <dt><span class="section"><a href="fixtures/case.html">Test case
  33         fixture</a></span></dt>
  34 <dt><span class="section"><a href="fixtures/per_test_suite_fixture.html">Test
  35         suite entry/exit fixture</a></span></dt>
  36 <dt><span class="section"><a href="fixtures/global.html">Global
  37         fixture</a></span></dt>
  38 </dl></div>
  39 <p>
  40         In general terms a test fixture or test context is the collection of one
  41         or more of the following items, required to perform the test:
  42       </p>
  43 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  44 <li class="listitem">
  45             preconditions
  46           </li>
  47 <li class="listitem">
  48             particular states of tested units
  49           </li>
  50 <li class="listitem">
  51             necessary cleanup procedures
  52           </li>
  53 </ul></div>
  54 <p>
  55         Though these tasks are encountered in many if not all test cases, what makes
  56         a test fixture different is repetition. Where a normal test case implementation
  57         does all preparatory and cleanup work itself, a test fixture allows it to
  58         be implemented in a separate reusable unit.
  59       </p>
  60 <p>
  61         With introduction of e<span class="bold"><strong>X</strong></span>treme <span class="bold"><strong>P</strong></span>rogramming
  62         (XP), the testing style, that require test setup/cleanup repetition, has
  63         become even more popular. Single XP adopted test modules may contain hundreds
  64         of single assertion test cases, many requiring very similar test setup/cleanup.
  65         This is the problem that the test fixture is designed to solve.
  66       </p>
  67 <p>
  68         In practice a test fixture usually is a combination of <code class="computeroutput"><span class="identifier">setup</span></code>
  69         and <code class="computeroutput"><span class="identifier">teardown</span></code> functions, associated
  70         with test case. The former serves the purposes of test setup. The later is
  71         dedicated to the cleanup tasks. Ideally we'd like for a test module author
  72         to be able to define variables used in fixtures on the stack and, at the
  73         same time, to refer to them directly in a test case.
  74       </p>
  75 <p>
  76         It's important to understand that C++ provides a way to implement a straightforward
  77         test fixture solution that almost satisfies our requirements without any
  78         extra support from the test framework. Here is how simple test module with
  79         such a fixture may look like:
  80       </p>
  81 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">MyFixture</span> <span class="special">{</span>
  82   <span class="identifier">MyFixture</span><span class="special">()</span>   <span class="special">{</span> <span class="identifier">i</span> <span class="special">=</span> <span class="keyword">new</span> <span class="keyword">int</span><span class="special">;</span> <span class="special">*</span><span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span> <span class="special">}</span>
  83   <span class="special">~</span><span class="identifier">MyFixture</span><span class="special">()</span>  <span class="special">{</span> <span class="keyword">delete</span> <span class="identifier">i</span><span class="special">;</span> <span class="special">}</span>
  84
  85   <span class="keyword">int</span><span class="special">*</span> <span class="identifier">i</span><span class="special">;</span>
  86 <span class="special">};</span>
  87
  88 <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_case1</span> <span class="special">)</span>
  89 <span class="special">{</span>
  90   <span class="identifier">MyFixture</span> <span class="identifier">f</span><span class="special">;</span>
  91   <span class="comment">// do something involving f.i</span>
  92 <span class="special">}</span>
  93
  94 <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_case2</span> <span class="special">)</span>
  95 <span class="special">{</span>
  96   <span class="identifier">MyFixture</span> <span class="identifier">f</span><span class="special">;</span>
  97   <span class="comment">// do something involving f.i</span>
  98 <span class="special">}</span>
  99 </pre>
 100 <p>
 101         This is a generic solution that can be used to implement any kind of shared
 102         setup or cleanup procedure. Still there are several more or less minor practical
 103         issues with this pure C++ based fixtures solution:
 104       </p>
 105 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 106 <li class="listitem">
 107             We need to add a fixture declaration statement into each test case manually.
 108           </li>
 109 <li class="listitem">
 110             Objects defined in fixture are references with <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">fixture</span><span class="special">-</span><span class="identifier">instance</span><span class="special">-</span><span class="identifier">name</span><span class="special">&gt;</span></code>
 111             prefix.
 112           </li>
 113 <li class="listitem">
 114             There is no place to execute a <span class="emphasis"><em>global</em></span> fixture, which
 115             performs <span class="emphasis"><em>global</em></span> setup/cleanup procedures before
 116             and after testing.
 117           </li>
 118 </ul></div>
 119 <p>
 120         The <span class="emphasis"><em>Unit Test Framework</em></span> lets you define a fixture according
 121         to <a class="link" href="fixtures/models.html" title="Fixture models">several
 122         generic interfaces</a>, and thus helps you with following tasks:
 123       </p>
 124 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 125 <li class="listitem">
 126             define shared setup/teardown procedures for a single or group of test
 127             cases
 128           </li>
 129 <li class="listitem">
 130             define setup/teardown procedures which are performed once per test suite
 131           </li>
 132 <li class="listitem">
 133             define <a class="link" href="fixtures/global.html" title="Global fixture">global
 134             setup/teardown</a> procedures which are performed once per test module
 135           </li>
 136 </ul></div>
 137 </div>
 138 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 139 <td align="left"></td>
 140 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 141       contributors<p>
 142         Distributed under the Boost Software License, Version 1.0. (See accompanying
 143         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>)
 144       </p>
 145 </div></td>
 146 </tr></table>
 147 <hr>
 148 <div class="spirit-nav">
 149 <a accesskey="p" href="decorators/explicit_decorator_declaration.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="fixtures/models.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 150 </div>
 151 </body>
 152 </html>