bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / test / doc / testing_tools / boost_test_reported_information.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:reports Reported information]


[/ ################################################ ]
[h3 Failure message, why?]

When an assertion fails, a message is logged containing:

* the body of the statement that failed
* the name of the file and the line of the failed assertion
* the name of the test case containing this assertion

The purpose of all these information is to isolate as quickly as possible the test that failed from the others. The *feedback*
that the execution of the test case provides is an important cue, for the following reasons:

* within the scheme of a continuous build/test, the logs available from the server contain this information, which points to
  a particular statement in the code
* the *cost* for reproducing an error is induced by the following steps:
  
  * identify the test module that failed in case there are many
  * compile and run the test module to reproduce the error
  * identify the line of the code that failed, 
  * fix the test directly if all the information is enough, or start a debug session 

We can see from the scheme above that reproduction of an error is /costly/, since usually one tends to reproduce the error,
which in turn induces at least the compilation of the test module. Also, a hidden cost is the lookup at the line of code
that contains the failing statement, which triggers a sequence of back and forth lookup between the log on one hand and the code
on the other hand.

The information extracted from the logs suggests the following fact: 

[tip Richness of the information contained in the logs is a key for the rapid understanding and the resolution of a failed statement]

[h3 Default reporting]
When an assertion fails, __BOOST_TEST__ reports details and values on the operands of `statement` that lead to the failure. 

[bt_example boost_test_macro3..BOOST_TEST reporting..run-fail]

In the above example, the values of the operands are reported for inspection, which is more valuable as a copy
of the full statement. However, we can observe that they are not treated symmetrically:

* "`a - 1 < b`" reports `"13 - 1 >= 12" failed`
* "`b > a - 1`" reports `"12 <= 12" failed`

More details on how the __UTF__ parses the statement are given in [link boost_test.testing_tools.internal_details this] section.


[h3 Custom messages]
While perfectly exact and precise, the file name, test case name, line number of a failed statement carries an information that 
is partial with regards to the meaning of the failed statement. 
Sometimes these information are not informative enough. The `BOOST_TEST` macro let you override the default message by the use of 
a second argument, as shown on the following example.

[bt_example boost_test_message..BOOST_TEST optional failure message..run-fail]

[endsect] [/ acceptable expressions]