ceph/src/boost/libs/test/doc/test_output/checkpoints.qbk

   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]