]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |