Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

libs/test/doc/testing_tools/boost_test_debugging.qbk

[/
 / Copyright (c) 2015 Boost.Test contributors
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]


[section:debugging Debugging the assertions]

In case you observe a failure in unit tests and you are using a debugger to determine the cause,
it may get really difficult to step into the expression inside an assertion. Because __BOOST_TEST__
builds an expression tree before evaluating it, the "Step Into" function of the debugger will have
to step into every step of building the expression tree before, you can go into the evaluation of
the expression.

In order to mitigate the problem, the test module can be build in the mode which disables the
building of expression trees inside assertions.
In this mode, the first thing the assertion does is to eagerly evaluate the tested expression.
You enable this mode by defining symbol __BOOST_TEST_TOOLS_UNDER_DEBUGGER__ (either with `#define`
or with compiler option `-D`) prior to including any of the __UTF__ headers.

[caution When the eager evaluation of expressions is turned on, the expressions are evaluated
['literally]: this automatically disables any special semantics,
 like tolerance for floating-point types or [classref boost::test_tools::per_element] versions
 of sequence comparisons. This may turn passing assertions into failing assertions and vice-versa.
 In the case of [classref boost::test_tools::per_element] comparisons of sequences, it may render an
 ill-formed program, if the sequences of different types are being compared.  ]

The inconvenience with __BOOST_TEST_TOOLS_UNDER_DEBUGGER__ is that you have to recompile the test module.
The __UTF__ gives you another option to compile two versions of the assertions and select the one to be used dynamically
depending on whether the test module is run under debugger or not.
This mode is enabled by defining symbol __BOOST_TEST_TOOLS_DEBUGGABLE__ (either with `#define` or with
compiler option `-D`) prior to the inclusion of any of the __UTF__ headers.

In order to determine if the test module is run under debugger or not, function
[link boost.debug.under_debugger `boost::debug::under_debugger`] is used.

[caution At present, function [link boost.debug.under_debugger `boost::debug::under_debugger`]
can correctly detect the debugger only on MSVC and a few Linux variants.]

[endsect] [/ debugging]