]>
Commit | Line | Data |
---|---|---|
1 | [/ | |
2 | / Copyright (c) 2015 Boost.Test contributors | |
3 | / | |
4 | / Distributed under the Boost Software License, Version 1.0. (See accompanying | |
5 | / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | /] | |
7 | ||
8 | ||
9 | [section:reports Reported information] | |
10 | ||
11 | ||
12 | [/ ################################################ ] | |
13 | [h3 Failure message, why?] | |
14 | ||
15 | When an assertion fails, a message is logged containing: | |
16 | ||
17 | * the body of the statement that failed | |
18 | * the name of the file and the line of the failed assertion | |
19 | * the name of the test case containing this assertion | |
20 | ||
21 | The purpose of all these information is to isolate as quickly as possible the test that failed from the others. The *feedback* | |
22 | that the execution of the test case provides is an important cue, for the following reasons: | |
23 | ||
24 | * within the scheme of a continuous build/test, the logs available from the server contain this information, which points to | |
25 | a particular statement in the code | |
26 | * the *cost* for reproducing an error is induced by the following steps: | |
27 | ||
28 | * identify the test module that failed in case there are many | |
29 | * compile and run the test module to reproduce the error | |
30 | * identify the line of the code that failed, | |
31 | * fix the test directly if all the information is enough, or start a debug session | |
32 | ||
33 | We can see from the scheme above that reproduction of an error is /costly/, since usually one tends to reproduce the error, | |
34 | which in turn induces at least the compilation of the test module. Also, a hidden cost is the lookup at the line of code | |
35 | that contains the failing statement, which triggers a sequence of back and forth lookup between the log on one hand and the code | |
36 | on the other hand. | |
37 | ||
38 | The information extracted from the logs suggests the following fact: | |
39 | ||
40 | [tip Richness of the information contained in the logs is a key for the rapid understanding and the resolution of a failed statement] | |
41 | ||
42 | [h3 Default reporting] | |
43 | When an assertion fails, __BOOST_TEST__ reports details and values on the operands of `statement` that lead to the failure. | |
44 | ||
45 | [bt_example boost_test_macro3..BOOST_TEST reporting..run-fail] | |
46 | ||
47 | In the above example, the values of the operands are reported for inspection, which is more valuable as a copy | |
48 | of the full statement. However, we can observe that they are not treated symmetrically: | |
49 | ||
50 | * "`a - 1 < b`" reports `"13 - 1 >= 12" failed` | |
51 | * "`b > a - 1`" reports `"12 <= 12" failed` | |
52 | ||
53 | More details on how the __UTF__ parses the statement are given in [link boost_test.testing_tools.internal_details this] section. | |
54 | ||
55 | ||
56 | [h3 Custom messages] | |
57 | While perfectly exact and precise, the file name, test case name, line number of a failed statement carries an information that | |
58 | is partial with regards to the meaning of the failed statement. | |
59 | Sometimes these information are not informative enough. The `BOOST_TEST` macro let you override the default message by the use of | |
60 | a second argument, as shown on the following example. | |
61 | ||
62 | [bt_example boost_test_message..BOOST_TEST optional failure message..run-fail] | |
63 | ||
64 | [endsect] [/ acceptable expressions] |