libs/test/doc/html/boost_test/testing_tools/debugging.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Debugging the assertions</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="../testing_tools.html" title="Writing unit tests">
   9 <link rel="prev" href="internal_details.html" title="BOOST_TEST: details on expressions">
  10 <link rel="next" href="summary.html" title="Summary of the API for writing tests">
  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="internal_details.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.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="summary.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.testing_tools.debugging"></a><a class="link" href="debugging.html" title="Debugging the assertions">Debugging the assertions</a>
  28 </h3></div></div></div>
  29 <p>
  30         In case you observe a failure in unit tests and you are using a debugger
  31         to determine the cause, it may get really difficult to step into the expression
  32         inside an assertion. Because <a class="link" href="../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> builds an expression
  33         tree before evaluating it, the "Step Into" function of the debugger
  34         will have to step into every step of building the expression tree before,
  35         you can go into the evaluation of the expression.
  36       </p>
  37 <p>
  38         In order to mitigate the problem, the test module can be build in the mode
  39         which disables the building of expression trees inside assertions. In this
  40         mode, the first thing the assertion does is to eagerly evaluate the tested
  41         expression. You enable this mode by defining symbol <a class="link" href="../utf_reference/testing_tool_ref/assertion_control_under_debugger.html" title="BOOST_TEST_TOOLS_UNDER_DEBUGGER"><code class="computeroutput"><span class="identifier">BOOST_TEST_TOOLS_UNDER_DEBUGGER</span></code></a>
  42         (either with <code class="computeroutput"><span class="preprocessor">#define</span></code> or
  43         with compiler option <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code>)
  44         prior to including any of the <span class="emphasis"><em>Unit Test Framework</em></span> headers.
  45       </p>
  46 <div class="caution"><table border="0" summary="Caution">
  47 <tr>
  48 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
  49 <th align="left">Caution</th>
  50 </tr>
  51 <tr><td align="left" valign="top"><p>
  52           When the eager evaluation of expressions is turned on, the expressions
  53           are evaluated <span class="emphasis"><em>literally</em></span>: this automatically disables
  54           any special semantics, like tolerance for floating-point types or <code class="computeroutput"><a class="link" href="../../boost/test_tools/per_element.html" title="Struct per_element">boost::test_tools::per_element</a></code>
  55           versions of sequence comparisons. This may turn passing assertions into
  56           failing assertions and vice-versa. In the case of <code class="computeroutput"><a class="link" href="../../boost/test_tools/per_element.html" title="Struct per_element">boost::test_tools::per_element</a></code>
  57           comparisons of sequences, it may render an ill-formed program, if the sequences
  58           of different types are being compared.
  59         </p></td></tr>
  60 </table></div>
  61 <p>
  62         The inconvenience with <a class="link" href="../utf_reference/testing_tool_ref/assertion_control_under_debugger.html" title="BOOST_TEST_TOOLS_UNDER_DEBUGGER"><code class="computeroutput"><span class="identifier">BOOST_TEST_TOOLS_UNDER_DEBUGGER</span></code></a>
  63         is that you have to recompile the test module. The <span class="emphasis"><em>Unit Test Framework</em></span>
  64         gives you another option to compile two versions of the assertions and select
  65         the one to be used dynamically depending on whether the test module is run
  66         under debugger or not. This mode is enabled by defining symbol <a class="link" href="../utf_reference/testing_tool_ref/assertion_control_under_debuggable.html" title="BOOST_TEST_TOOLS_DEBUGGABLE"><code class="computeroutput"><span class="identifier">BOOST_TEST_TOOLS_DEBUGGABLE</span></code></a> (either
  67         with <code class="computeroutput"><span class="preprocessor">#define</span></code> or with compiler
  68         option <code class="computeroutput"><span class="special">-</span><span class="identifier">D</span></code>)
  69         prior to the inclusion of any of the <span class="emphasis"><em>Unit Test Framework</em></span>
  70         headers.
  71       </p>
  72 <p>
  73         In order to determine if the test module is run under debugger or not, function
  74         <a class="link" href="../../boost/debug/under_debugger.html" title="Function under_debugger"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">debug</span><span class="special">::</span><span class="identifier">under_debugger</span></code></a>
  75         is used.
  76       </p>
  77 <div class="caution"><table border="0" summary="Caution">
  78 <tr>
  79 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
  80 <th align="left">Caution</th>
  81 </tr>
  82 <tr><td align="left" valign="top"><p>
  83           At present, function <a class="link" href="../../boost/debug/under_debugger.html" title="Function under_debugger"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">debug</span><span class="special">::</span><span class="identifier">under_debugger</span></code></a> can correctly detect
  84           the debugger only on MSVC and a few Linux variants.
  85         </p></td></tr>
  86 </table></div>
  87 </div>
  88 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
  89 <td align="left"></td>
  90 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
  91       contributors<p>
  92         Distributed under the Boost Software License, Version 1.0. (See accompanying
  93         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>)
  94       </p>
  95 </div></td>
  96 </tr></table>
  97 <hr>
  98 <div class="spirit-nav">
  99 <a accesskey="p" href="internal_details.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../testing_tools.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="summary.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 100 </div>
 101 </body>
 102 </html>