12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364 |
- [/
- / 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 carry 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]
|