3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Checkpoints for accurate failure location</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_tools_support_for_logging.html" title="Tools supports for logging">
9 <link rel="prev" href="test_output_macro_message.html" title="Custom messages">
10 <link rel="next" href="contexts.html" title="Contexts">
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="test_output_macro_message.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tools_support_for_logging.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="contexts.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.test_output.test_tools_support_for_logging.checkpoints"></a><a class="link" href="checkpoints.html" title="Checkpoints for accurate failure location">Checkpoints
28 for accurate failure location</a>
29 </h4></div></div></div>
31 In most cases, the <span class="emphasis"><em>Unit Test Framework</em></span> can't provide
32 an exact location where system error occurs or uncaught C++ exception is
33 thrown from. To be able to pinpoint it as close as possible the <span class="emphasis"><em>Unit
34 Test Framework</em></span> keeps track of <span class="bold"><strong>checkpoints</strong></span>
35 - the location a test module passed through.
38 The <span class="emphasis"><em>Unit Test Framework</em></span> keeps track of checkpoints
39 at test case entrance, exit, fixture initialization, and at test tool invocation
43 Any other checkpoints should be entered by you manually if you need more
44 granularity in case a fatal error occurs during the test. The <span class="emphasis"><em>Unit
45 Test Framework</em></span> provides two macros for this purpose:
47 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
49 <a class="link" href="checkpoints.html#ref_named_checkpoint"><code class="computeroutput"><span class="identifier">BOOST_TEST_CHECKPOINT</span></code></a>
50 to specify a <span class="emphasis"><em>named</em></span> checkpoint and
53 <a class="link" href="checkpoints.html#ref_unnamed_checkpoint"><code class="computeroutput"><span class="identifier">BOOST_TEST_PASSPOINT</span></code></a>
54 to specify an <span class="emphasis"><em>unnamed</em></span> checkpoint.
58 The checkpoints are also convenient for checks in loops as they might provide
59 more information about the occurrence of a failure (although superseded
60 by [links boost_test.test_output.test_tools_support_for_logging.contexts
63 <a name="ref_named_checkpoint"></a><h4>
64 <a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.h0"></a>
65 <span class="phrase"><a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.named_checkpoints"></a></span><a class="link" href="checkpoints.html#boost_test.test_output.test_tools_support_for_logging.checkpoints.named_checkpoints">Named
69 The macro <a class="link" href="../../utf_reference/testout_reference/test_output_macro_checkpoint.html" title="BOOST_TEST_CHECKPOINT"><code class="computeroutput"><span class="identifier">BOOST_TEST_CHECKPOINT</span></code></a> is intended
70 to be used to inject <span class="bold"><strong>named</strong></span> checkpoint
71 position. The macro signature is as follows:
73 <pre class="programlisting"><a class="link" href="../../utf_reference/testout_reference/test_output_macro_checkpoint.html" title="BOOST_TEST_CHECKPOINT"><code class="computeroutput"><span class="identifier">BOOST_TEST_CHECKPOINT</span></code></a><span class="special">(</span><span class="identifier">checkpoint_message</span><span class="special">);</span>
76 The message formatted at the checkpoint position is saved and reported
77 by the exception logging functions (if any occurs). Similarly to the <a class="link" href="../../utf_reference/testout_reference/test_output_macro_message.html" title="BOOST_TEST_MESSAGE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MESSAGE</span></code></a> the message
78 can be formatted from any standard output stream compliant components.
81 <a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.h1"></a>
82 <span class="phrase"><a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.example_descr"></a></span><a class="link" href="checkpoints.html#boost_test.test_output.test_tools_support_for_logging.checkpoints.example_descr">Example:
83 <code class="computeroutput"><span class="identifier">BOOST_TEST_CHECKPOINT</span></code> usage</a>
85 <div class="informaltable"><table class="table">
86 <colgroup><col></colgroup>
93 <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>
94 <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>
96 <span class="keyword">extern</span> <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">);</span>
98 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_external_interface</span> <span class="special">)</span>
99 <span class="special">{</span>
100 <span class="keyword">for</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">3</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="identifier">i</span><span class="special">--</span> <span class="special">)</span> <span class="special">{</span>
101 <span class="identifier">BOOST_TEST_CHECKPOINT</span><span class="special">(</span> <span class="string">"Calling 'foo' with i="</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special">);</span>
102 <span class="identifier">foo</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">);</span>
103 <span class="special">}</span>
104 <span class="special">}</span>
106 <span class="keyword">void</span> <span class="identifier">goo</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">value</span> <span class="special">)</span>
107 <span class="special">{</span>
108 <span class="identifier">BOOST_TEST_CHECKPOINT</span><span class="special">(</span> <span class="string">"Inside goo with value '"</span> <span class="special"><<</span> <span class="identifier">value</span> <span class="special"><<</span> <span class="string">"'"</span><span class="special">);</span>
109 <span class="special">}</span>
111 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">)</span>
112 <span class="special">{</span>
113 <span class="keyword">if</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">1</span> <span class="special">)</span>
114 <span class="keyword">throw</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">(</span><span class="string">"Undefined Behaviour ahead!"</span><span class="special">);</span>
115 <span class="comment">// following line may not raise an exception on some compilers:</span>
116 <span class="comment">// Undefined Behaviour is implementation specific</span>
117 <span class="identifier">goo</span><span class="special">(</span> <span class="number">2</span><span class="special">/(</span><span class="identifier">i</span><span class="special">-</span><span class="number">1</span><span class="special">)</span> <span class="special">);</span>
118 <span class="special">}</span>
122 <div class="informaltable"><table class="table">
123 <colgroup><col></colgroup>
130 <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>
131 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
132 <span class="identifier">unknown</span> <span class="identifier">location</span><span class="special">(</span><span class="number">0</span><span class="special">):</span> <span class="identifier">fatal</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_external_interface"</span><span class="special">:</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span><span class="special">:</span> <span class="identifier">Undefined</span> <span class="identifier">Behaviour</span> <span class="identifier">ahead</span><span class="special">!</span>
133 <span class="special">../</span><span class="identifier">doc</span><span class="special">/</span><span class="identifier">examples</span><span class="special">/</span><span class="identifier">example22</span><span class="special">.</span><span class="identifier">run</span><span class="special">-</span><span class="identifier">fail</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">17</span><span class="special">):</span> <span class="identifier">last</span> <span class="identifier">checkpoint</span><span class="special">:</span> <span class="identifier">Calling</span> <span class="char">'foo'</span> <span class="identifier">with</span> <span class="identifier">i</span><span class="special">=</span><span class="number">1</span>
135 <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">"example"</span>
139 <a name="ref_unnamed_checkpoint"></a><h4>
140 <a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.h2"></a>
141 <span class="phrase"><a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.unnamed_checkpoints"></a></span><a class="link" href="checkpoints.html#boost_test.test_output.test_tools_support_for_logging.checkpoints.unnamed_checkpoints">Unnamed
145 The macro <a class="link" href="../../utf_reference/testout_reference/test_output_macro_passpoint.html" title="BOOST_TEST_PASSPOINT"><code class="computeroutput"><span class="identifier">BOOST_TEST_PASSPOINT</span></code></a> is intended
146 to be used to inject an <span class="bold"><strong>unnamed</strong></span> checkpoint
147 position. The macro signature is as follows:
149 <pre class="programlisting"><a class="link" href="../../utf_reference/testout_reference/test_output_macro_passpoint.html" title="BOOST_TEST_PASSPOINT"><code class="computeroutput"><span class="identifier">BOOST_TEST_PASSPOINT</span></code></a><span class="special">();</span>
152 Unlike the macro <a class="link" href="../../utf_reference/testout_reference/test_output_macro_checkpoint.html" title="BOOST_TEST_CHECKPOINT"><code class="computeroutput"><span class="identifier">BOOST_TEST_CHECKPOINT</span></code></a> this macro
153 doesn't require any message to be supplied with it. It's just a simple
154 "been there" marker that records file name and line number code
158 <a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.h3"></a>
159 <span class="phrase"><a name="boost_test.test_output.test_tools_support_for_logging.checkpoints.example_descr0"></a></span><a class="link" href="checkpoints.html#boost_test.test_output.test_tools_support_for_logging.checkpoints.example_descr0">Example:
160 <code class="computeroutput"><span class="identifier">BOOST_TEST_PASSPOINT</span></code> usage</a>
162 <div class="informaltable"><table class="table">
163 <colgroup><col></colgroup>
170 <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>
171 <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>
173 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">value</span> <span class="special">)</span> <span class="special">{</span>
174 <span class="identifier">BOOST_TEST_CHECKPOINT</span><span class="special">(</span><span class="string">"Inside foo with value '"</span> <span class="special"><<</span> <span class="identifier">value</span> <span class="special"><<</span> <span class="string">"' (should not be there)"</span><span class="special">);</span>
175 <span class="special">}</span>
177 <span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_case</span> <span class="special">)</span>
178 <span class="special">{</span>
179 <span class="keyword">int</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
181 <span class="identifier">BOOST_TEST_PASSPOINT</span><span class="special">();</span>
182 <span class="special">++</span><span class="identifier">p</span><span class="special">;</span>
184 <span class="identifier">BOOST_TEST_PASSPOINT</span><span class="special">();</span>
185 <span class="special">++</span><span class="identifier">p</span><span class="special">;</span>
187 <span class="identifier">BOOST_TEST_PASSPOINT</span><span class="special">();</span>
188 <span class="identifier">foo</span><span class="special">(</span> <span class="special">*</span><span class="identifier">p</span> <span class="special">);</span>
189 <span class="special">}</span>
193 <div class="informaltable"><table class="table">
194 <colgroup><col></colgroup>
201 <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>
202 <span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
203 <span class="identifier">unknown</span> <span class="identifier">location</span><span class="special">(</span><span class="number">0</span><span class="special">):</span> <span class="identifier">fatal</span> <span class="identifier">error</span> <span class="identifier">in</span> <span class="string">"test_case"</span><span class="special">:</span> <span class="identifier">memory</span> <span class="identifier">access</span> <span class="identifier">violation</span> <span class="identifier">at</span> <span class="identifier">address</span><span class="special">:</span> <span class="number">0x00000008</span><span class="special">:</span> <span class="identifier">no</span> <span class="identifier">mapping</span> <span class="identifier">at</span> <span class="identifier">fault</span> <span class="identifier">address</span>
204 <span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">16</span><span class="special">):</span> <span class="identifier">last</span> <span class="identifier">checkpoint</span>
206 <span class="special">***</span> <span class="number">1</span> <span class="identifier">failures</span> <span class="identifier">is</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>
211 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
212 <td align="left"></td>
213 <td align="right"><div class="copyright-footer">Copyright © 2001-2019 Boost.Test
215 Distributed under the Boost Software License, Version 1.0. (See accompanying
216 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>)
221 <div class="spirit-nav">
222 <a accesskey="p" href="test_output_macro_message.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../test_tools_support_for_logging.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="contexts.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>