]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | / Copyright (c) 2001 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 | [section:checkpoints Checkpoints for accurate failure location] | |
9 | ||
10 | In most cases, the __UTF__ can't provide an exact location where system error occurs or uncaught C++ exception | |
11 | is thrown from. To be able to pinpoint it as close as possible the __UTF__ keeps track of *checkpoints* - the | |
12 | location a test module passed through. | |
13 | ||
14 | The __UTF__ keeps track of checkpoints at test case entrance, exit, fixture initialization, and at test tool invocation point. | |
15 | ||
16 | Any other checkpoints should be entered by you manually if you need more granularity in case a fatal | |
17 | error occurs during the test. The __UTF__ provides two macros for this purpose: | |
18 | ||
19 | * [link ref_named_checkpoint `BOOST_TEST_CHECKPOINT`] to specify a ['named] checkpoint and | |
20 | * [link ref_unnamed_checkpoint `BOOST_TEST_PASSPOINT`] to specify an ['unnamed] checkpoint. | |
21 | ||
22 | The checkpoints are also convenient for checks in loops as they might provide | |
23 | more information about the occurrence of a failure (although superseded by | |
24 | [links boost_test.test_output.test_tools_support_for_logging.contexts contexts]). | |
25 | ||
26 | [/ -------------------------------------------------------------------------------------------------- ] | |
27 | [#ref_named_checkpoint][h3 Named checkpoints] | |
28 | ||
29 | The macro __BOOST_TEST_CHECKPOINT__ is intended to be used to inject [*named] checkpoint position. The | |
30 | macro signature is as follows: | |
31 | ||
32 | `` | |
33 | __BOOST_TEST_CHECKPOINT__(checkpoint_message); | |
34 | `` | |
35 | ||
36 | The message formatted at the checkpoint position is saved and reported by the exception logging functions (if any | |
37 | occurs). Similarly to the __BOOST_TEST_MESSAGE__ the message can be formatted from any standard | |
38 | output stream compliant components. | |
39 | ||
40 | [bt_example example22..__BOOST_TEST_CHECKPOINT__ usage..run-fail] | |
41 | ||
42 | ||
43 | [/ -------------------------------------------------------------------------------------------------- ] | |
44 | [#ref_unnamed_checkpoint][h3 Unnamed checkpoints] | |
45 | ||
46 | The macro __BOOST_TEST_PASSPOINT__ is intended to be used to inject an [*unnamed] checkpoint position. The | |
47 | macro signature is as follows: | |
48 | ||
49 | `` | |
50 | __BOOST_TEST_PASSPOINT__(); | |
51 | `` | |
52 | ||
53 | Unlike the macro __BOOST_TEST_CHECKPOINT__ this macro doesn't require any message to be | |
54 | supplied with it. It's just a simple "been there" marker that records file name and line number | |
55 | code passes through. | |
56 | ||
57 | [bt_example example23..__BOOST_TEST_PASSPOINT__ usage..run-fail] | |
58 | ||
59 | [endsect] [/checkpoints] |