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 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]