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