3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Test case fixture</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="models.html" title="Fixture models">
10 <link rel="next" href="per_test_suite_fixture.html" title="Test suite entry/exit fixture">
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>
22 <div class="spirit-nav">
23 <a accesskey="p" href="models.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="per_test_suite_fixture.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="boost_test.tests_organization.fixtures.case"></a><a class="link" href="case.html" title="Test case fixture">Test case
29 </h4></div></div></div>
31 A <span class="emphasis"><em>test case fixture</em></span> is a fixture consumed by a test
32 case: the fixture <code class="computeroutput"><span class="identifier">setup</span></code>
33 is called before the test case executes, and the fixture <code class="computeroutput"><span class="identifier">teardown</span></code> is called after the test case
34 finished its execution, independently from its execution state.
37 The <span class="emphasis"><em>Unit Test Framework</em></span> provides several ways of defining
38 fixtures for test-cases, each of which having their properties:
40 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
42 the declaration of a fixture for a single test case, letting the test
43 case access the members of the fixture,
46 the declaration of one or more fixture(s) for a single test case, without
47 accessing the members and with a flexible interface,
50 the declaration of a fixture for a group of test-cases defined by a
51 subtree, with access to the members of the fixture.
55 <a name="boost_test.tests_organization.fixtures.case.h0"></a>
56 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.single_test_case_fixture"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.single_test_case_fixture">Single
60 The following two methods are available for declaring a fixture attached
61 to one particular test case:
63 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
65 the use of the macro <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> in
66 place of <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>, which
67 let access to the members of the fixture
70 the use of 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>, which does not let
71 access to the members but enables the definition of several fixtures
75 <a name="test_case_fixture_macro"></a><h5>
76 <a name="boost_test.tests_organization.fixtures.case.h1"></a>
77 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.fixture_with_boost_fixture_test_"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.fixture_with_boost_fixture_test_">Fixture
78 with <code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span></code></a>
81 <code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span></code>
82 serves as a test case declaration with a fixture, and is meant be used
83 in place of the test case declaration with <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>:
85 <pre class="programlisting"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case_name</span><span class="special">,</span> <span class="identifier">fixture_name</span><span class="special">);</span>
88 The only difference from 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> is the presence
89 of an extra argument <code class="computeroutput"><span class="identifier">fixture_name</span></code>.
90 The public and protected members of the fixture are directly accessible
91 from the test case body. Only one fixture can be attached to a test-case
92 <a href="#ftn.boost_test.tests_organization.fixtures.case.f0" class="footnote" name="boost_test.tests_organization.fixtures.case.f0"><sup class="footnote">[4]</sup></a>.
94 <div class="note"><table border="0" summary="Note">
96 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
97 <th align="left">Note</th>
99 <tr><td align="left" valign="top"><p>
100 You can't access private members of fixture, but then why would you make
105 <a name="boost_test.tests_organization.fixtures.case.h2"></a>
106 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.example_descr"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.example_descr">Example:
107 Per test case fixture</a>
109 <div class="informaltable"><table class="table">
110 <colgroup><col></colgroup>
117 <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>
118 <span class="preprocessor">#include</span> <span class="special"><</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">></span>
120 <span class="keyword">struct</span> <span class="identifier">F</span> <span class="special">{</span>
121 <span class="identifier">F</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> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span> <span class="string">"setup fixture"</span> <span class="special">);</span> <span class="special">}</span>
122 <span class="special">~</span><span class="identifier">F</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span> <span class="string">"teardown fixture"</span> <span class="special">);</span> <span class="special">}</span>
124 <span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
125 <span class="special">};</span>
127 <span class="identifier">BOOST_FIXTURE_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case1</span><span class="special">,</span> <span class="identifier">F</span> <span class="special">)</span>
128 <span class="special">{</span>
129 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">1</span> <span class="special">);</span>
130 <span class="special">++</span><span class="identifier">i</span><span class="special">;</span>
131 <span class="special">}</span>
133 <span class="identifier">BOOST_FIXTURE_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case2</span><span class="special">,</span> <span class="identifier">F</span> <span class="special">)</span>
134 <span class="special">{</span>
135 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span> <span class="identifier">i</span><span class="special">,</span> <span class="number">1</span> <span class="special">);</span>
136 <span class="special">}</span>
138 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case3</span> <span class="special">)</span>
139 <span class="special">{</span>
140 <span class="identifier">BOOST_TEST</span><span class="special">(</span> <span class="keyword">true</span> <span class="special">);</span>
141 <span class="special">}</span>
145 <div class="informaltable"><table class="table">
146 <colgroup><col></colgroup>
153 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">example</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">message</span>
154 <span class="identifier">Running</span> <span class="number">3</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
155 <span class="identifier">setup</span> <span class="identifier">fixture</span>
156 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_case1"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">1</span> <span class="identifier">has</span> <span class="identifier">failed</span>
157 <span class="identifier">teardown</span> <span class="identifier">fixture</span>
158 <span class="identifier">setup</span> <span class="identifier">fixture</span>
159 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">19</span><span class="special">):</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_case2"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">1</span> <span class="identifier">has</span> <span class="identifier">failed</span> <span class="special">[</span><span class="number">0</span> <span class="special">!=</span> <span class="number">1</span><span class="special">]</span>
160 <span class="identifier">teardown</span> <span class="identifier">fixture</span>
162 <span class="special">***</span> <span class="number">2</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">test</span> <span class="identifier">suite</span> <span class="string">"example"</span>
167 In this example only <code class="computeroutput"><span class="identifier">test_case1</span></code>
168 and <code class="computeroutput"><span class="identifier">test_case2</span></code> have fixture
169 <code class="computeroutput"><span class="identifier">F</span></code> assigned. You still need
170 to refer to the fixture name in every test case. <a class="link" href="case.html#test_case_fixture_subtree">This</a>
171 section explains how a same fixture can be declared for a subtree under
174 <a name="test_case_fixture_decorator"></a><h5>
175 <a name="boost_test.tests_organization.fixtures.case.h3"></a>
176 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.fixture_with_fixture_decorator"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.fixture_with_fixture_decorator">Fixture
177 with <code class="computeroutput"><span class="identifier">fixture</span></code> decorator</a>
180 By 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>, it is possible to:
182 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
183 <li class="listitem">
184 attach several fixtures to a unique test case
186 <li class="listitem">
187 use a flexible fixture interface (see <a class="link" href="models.html" title="Fixture models">here</a>)
190 <div class="note"><table border="0" summary="Note">
192 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
193 <th align="left">Note</th>
195 <tr><td align="left" valign="top"><p>
196 Using the decorator approach, it is not possible to access the members
197 of the fixture (in case the fixture is implemented as a class)
200 <a name="test_case_fixture_subtree"></a><h4>
201 <a name="boost_test.tests_organization.fixtures.case.h4"></a>
202 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.fixture_for_a_complete_subtree"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.fixture_for_a_complete_subtree">Fixture
203 for a complete subtree</a>
206 If all test cases in a test sub tree require the same fixture (you can
207 group test cases in a test suite based on a fixture required) you can make
208 another step toward an automation of a test fixture assignment. To assign
209 the same shared fixture for all test cases in a test suite, use the macro
210 <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> in place
211 of the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_suite.html" title="BOOST_AUTO_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_SUITE</span></code></a> for automated
212 test suite creation and registration.
214 <pre class="programlisting"><span class="identifier">BOOST_FIXTURE_TEST_SUITE</span><span class="special">(</span><span class="identifier">suite_name</span><span class="special">,</span> <span class="identifier">fixture_name</span><span class="special">);</span>
217 Once again the only difference from the macro <a class="link" href="../../utf_reference/test_org_reference/test_org_boost_auto_test_suite.html" title="BOOST_AUTO_TEST_SUITE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_SUITE</span></code></a> usage is
218 the presence of an extra argument - the fixture name. And now, you not
219 only have direct access to the public and protected members of the fixture,
220 but also do not need to refer to the fixture name in test case definition.
221 All test cases assigned the same fixture automatically.
223 <div class="tip"><table border="0" summary="Tip">
225 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
226 <th align="left">Tip</th>
228 <tr><td align="left" valign="top"><p>
229 If necessary you can reset the fixture for a particular test case using
230 the macro <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>. Similarly
231 you can reset the fixture for a particular sub test suite using <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>.
234 <div class="note"><table border="0" summary="Note">
236 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
237 <th align="left">Note</th>
239 <tr><td align="left" valign="top"><p>
240 The fixture assignment is <span class="emphasis"><em>deep</em></span>. In other words unless
241 reset by another <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> or
242 <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> definition
243 the same fixture is assigned to all test cases of a test suite, including
244 ones that belong to the sub test suites.
248 <a name="boost_test.tests_organization.fixtures.case.h5"></a>
249 <span class="phrase"><a name="boost_test.tests_organization.fixtures.case.example_descr0"></a></span><a class="link" href="case.html#boost_test.tests_organization.fixtures.case.example_descr0">Example:
250 Test suite level fixture</a>
252 <div class="informaltable"><table class="table">
253 <colgroup><col></colgroup>
260 <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">fixture_02</span>
261 <span class="preprocessor">#include</span> <span class="special"><</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">></span>
263 <span class="keyword">struct</span> <span class="identifier">F</span> <span class="special">{</span>
264 <span class="identifier">F</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> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span> <span class="string">"setup fixture"</span> <span class="special">);</span> <span class="special">}</span>
265 <span class="special">~</span><span class="identifier">F</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span> <span class="string">"teardown fixture"</span> <span class="special">);</span> <span class="special">}</span>
267 <span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
268 <span class="special">};</span>
270 <span class="identifier">BOOST_FIXTURE_TEST_SUITE</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> <span class="identifier">F</span><span class="special">)</span>
272 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case1</span><span class="special">)</span>
273 <span class="special">{</span>
274 <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"running test_case1"</span><span class="special">);</span>
275 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
276 <span class="special">}</span>
278 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case2</span><span class="special">)</span>
279 <span class="special">{</span>
280 <span class="identifier">BOOST_TEST_MESSAGE</span><span class="special">(</span><span class="string">"running test_case2"</span><span class="special">);</span>
281 <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
282 <span class="special">}</span>
284 <span class="identifier">BOOST_AUTO_TEST_SUITE_END</span><span class="special">()</span>
288 <div class="informaltable"><table class="table">
289 <colgroup><col></colgroup>
296 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">></span> <span class="identifier">fixture_02</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">message</span>
297 <span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
298 <span class="identifier">setup</span> <span class="identifier">fixture</span>
299 <span class="identifier">running</span> <span class="identifier">test_case1</span>
300 <span class="identifier">teardown</span> <span class="identifier">fixture</span>
301 <span class="identifier">setup</span> <span class="identifier">fixture</span>
302 <span class="identifier">running</span> <span class="identifier">test_case2</span>
303 <span class="identifier">teardown</span> <span class="identifier">fixture</span>
305 <span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
309 <div class="caution"><table border="0" summary="Caution">
311 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
312 <th align="left">Caution</th>
314 <tr><td align="left" valign="top"><p>
315 The fixture constructor/setup and teardown/destructor is called for each
316 test cases (the state of the fixture is not shared among the test cases).
319 <div class="footnotes">
320 <br><hr style="width:100; text-align:left;margin-left: 0">
321 <div id="ftn.boost_test.tests_organization.fixtures.case.f0" class="footnote"><p><a href="#boost_test.tests_organization.fixtures.case.f0" class="para"><sup class="para">[4] </sup></a>
322 it is still possible to define a class inheriting from several fixtures,
323 that will act as a proxy fixture.
327 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
328 <td align="left"></td>
329 <td align="right"><div class="copyright-footer">Copyright © 2001-2019 Boost.Test
331 Distributed under the Boost Software License, Version 1.0. (See accompanying
332 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>)
337 <div class="spirit-nav">
338 <a accesskey="p" href="models.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="per_test_suite_fixture.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>