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

   1 [/
   2  / Copyright (c) 2003 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:logging_api Logging API]
   9
  10 While many test log configuration tasks can be performed at runtime using predefined framework parameters, the
  11 __UTF__ provides a compile time interface as well. The interface gives you full power over what, where and how to
  12 log. The interface is provided by singleton class [classref boost::unit_test::unit_test_log_t] and is
  13 accessible through local file scope reference to single instance of this class
  14
  15 ``boost::unit_test::unit_test_log``
  16
  17
  18 [/ ------------------------------------------------------------------------------------------------ ]
  19
  20 [section:log_ct_output_stream_redirection Log output stream redirection]
  21
  22 If you want to redirect the test log output stream into something different from the logger default output stream
  23 (usually `std::cout`, `std::cerr` or a file), use the following interface:
  24
  25 ``
  26   boost::unit_test::unit_test_log.set_stream( std::ostream& );
  27 ``
  28
  29 or for a particular log format:
  30
  31 ``
  32   boost::unit_test::unit_test_log.set_stream( boost::unit_test::output_format, std::ostream& );
  33 ``
  34
  35 [tip See [memberref boost::unit_test::unit_test_log_t::set_stream] and [enumref boost::unit_test::output_format] for more details]
  36
  37 You can reset the output stream at any time both during the test module initialization and from within test
  38 cases. There are no limitations on number of output stream resets neither.
  39
  40 [warning
  41   If you redirect test log output stream from global fixture setup, you are [*required] to reset it back to `std::cout`
  42   during teardown to prevent dangling references access]
  43
  44 [bt_example example50..Compile-time log output redirection..run-fail]
  45
  46 [endsect] [/section:log_ct_output_stream_redirection]
  47
  48
  49 [/ ------------------------------------------------------------------------------------------------ ]
  50 [#ref_log_level_explanations][section:log_ct_log_level Log level configuration]
  51 If you need to enforce specific log level from within your test module use the following interface:
  52
  53 ``
  54   boost::unit_test::unit_test_log.set_threshold_level( boost::unit_test::log_level );
  55 ``
  56
  57 or for a specific logger:
  58
  59 ``
  60   boost::unit_test::unit_test_log.set_threshold_level( boost::unit_test::output_format, boost::unit_test::log_level );
  61 ``
  62
  63
  64 [tip See [memberref boost::unit_test::unit_test_log_t::set_threshold_level] and [enumref boost::unit_test::output_format] for more details]
  65
  66 In regular circumstances you shouldn't use this interface, since you not only override default log level, but also
  67 the one supplied at test execution time. Prefer to use runtime parameters
  68 [link boost_test.utf_reference.rt_param_reference.log_level `--log_level`] or [link boost_test.utf_reference.rt_param_reference.logger `--logger`]
  69 for log level selection.
  70
  71 [bt_example example51..Compile-time log level configuration..run]
  72
  73 [endsect] [/section:log_ct_log_level]
  74
  75 [/ ------------------------------------------------------------------------------------------------ ]
  76 [section:log_ct_log_format Predefined log format selection]
  77 The select at compile time the log format from the list of the formats supplied by the __UTF__
  78
  79 ``
  80    boost::unit_test::unit_test_log.set_format( boost::unit_test::output_format );
  81 ``
  82
  83 or for adding a format:
  84
  85 ``
  86    boost::unit_test::unit_test_log.add_format( boost::unit_test::output_format );
  87 ``
  88
  89 [caution [memberref boost::unit_test::unit_test_log_t::set_format] above disables all formatters but the one provided as argument.]
  90
  91 [tip See [memberref boost::unit_test::unit_test_log_t::set_format] and [enumref boost::unit_test::output_format] for more details]
  92
  93 In regular circumstances you shouldn't use this interface. Prefer to use runtime parameters
  94 [link boost_test.utf_reference.rt_param_reference.log_format `--log_format`] or [link boost_test.utf_reference.rt_param_reference.logger `--logger`]
  95 for predefined log format selection.
  96
  97 [bt_example example52..Compile-time log format selection..run-fail]
  98
  99 [endsect] [/section:log_ct_log_format]
 100
 101 [/ ------------------------------------------------------------------------------------------------ ]
 102 [#ref_log_formatter_api][section:custom_log_formatter Custom log format support]
 103
 104 It is possible to implement your own formatter: it should derive from [classref boost::unit_test::unit_test_log_formatter].
 105
 106 It is possible to add a your own instance of a formatter to the set of formats using one of the two functions:
 107
 108 ``
 109 boost::unit_test::unit_test_log.set_formatter( unit_test_log_formatter* );
 110 boost::unit_test::unit_test_log.add_formatter( unit_test_log_formatter* );
 111 ``
 112
 113 [tip See [memberref boost::unit_test::unit_test_log_t::set_formatter] and [memberref boost::unit_test::unit_test_log_t::add_formatter]
 114  for more details]
 115
 116 [warning The call to `boost::unit_test::unit_test_log.set_formatter` is equivalent to
 117  [memberref boost::unit_test::unit_test_log_t::set_format] ([link boost_test.test_output.logging_api.log_ct_log_format see here])
 118  as it disables all other formatters.]
 119
 120 [tip More details about the class implementing the formatting of the logs can be found in the following reference sections:
 121
 122 * [classref boost::unit_test::unit_test_log_formatter] defines the interface for all loggers. Built-in
 123   [link boost_test.test_output.log_formats.log_human_readable_format HRF], [link boost_test.test_output.log_formats.log_xml_format XML]
 124   and [link boost_test.test_output.log_formats.log_junit_format JUNIT] loggers derive from this class
 125 * [classref boost::unit_test::test_results] defines the information carried by the tests to provide reports and logs.
 126 ]
 127
 128 [endsect] [/section:custom_log_formatter]
 129
 130
 131 [endsect] [/section:logging_api]