1 | // (C) Copyright Gennadiy Rozental 2001. |
2 | // Distributed under the Boost Software License, Version 1.0. |
3 | // (See accompanying file LICENSE_1_0.txt or copy at |
4 | // http://www.boost.org/LICENSE_1_0.txt) |
5 | |
6 | // See http://www.boost.org/libs/test for the library home page. |
7 | // |
8 | /// @file |
9 | /// @brief Defines unit test log formatter interface |
10 | /// |
11 | /// You can define a class with implements this interface and use an instance of it |
12 | /// as a Unit Test Framework log formatter |
13 | // *************************************************************************** |
14 | |
15 | #ifndef BOOST_TEST_UNIT_TEST_LOG_FORMATTER_HPP_071894GER |
16 | #define BOOST_TEST_UNIT_TEST_LOG_FORMATTER_HPP_071894GER |
17 | |
18 | // Boost.Test |
19 | #include <boost/test/detail/global_typedef.hpp> |
20 | #include <boost/test/detail/log_level.hpp> |
21 | #include <boost/test/detail/fwd_decl.hpp> |
22 | |
23 | // STL |
24 | #include <iosfwd> |
25 | #include <string> // for std::string |
26 | |
27 | #include <boost/test/detail/suppress_warnings.hpp> |
28 | |
29 | //____________________________________________________________________________// |
30 | |
31 | namespace boost { |
32 | namespace unit_test { |
33 | |
34 | // ************************************************************************** // |
35 | /// Collection of log entry attributes |
36 | // ************************************************************************** // |
37 | |
38 | struct BOOST_TEST_DECL log_entry_data { |
39 | log_entry_data() |
40 | { |
41 | m_file_name.reserve( res_arg: 200 ); |
42 | } |
43 | |
44 | std::string m_file_name; ///< log entry file name |
45 | std::size_t m_line_num; ///< log entry line number |
46 | log_level m_level; ///< log entry level |
47 | |
48 | void clear() |
49 | { |
50 | m_file_name.erase(); |
51 | m_line_num = 0; |
52 | m_level = log_nothing; |
53 | } |
54 | }; |
55 | |
56 | // ************************************************************************** // |
57 | /// Collection of log checkpoint attributes |
58 | // ************************************************************************** // |
59 | |
60 | struct BOOST_TEST_DECL log_checkpoint_data |
61 | { |
62 | const_string m_file_name; ///< log checkpoint file name |
63 | std::size_t m_line_num; ///< log checkpoint file name |
64 | std::string m_message; ///< log checkpoint message |
65 | |
66 | void clear() |
67 | { |
68 | m_file_name.clear(); |
69 | m_line_num = 0; |
70 | m_message = std::string(); |
71 | } |
72 | }; |
73 | |
74 | // ************************************************************************** // |
75 | /// Abstract Unit Test Framework log formatter interface |
76 | |
77 | /// During the test module execution Unit Test Framework can report messages about success or failure of assertions, |
78 | /// which test suites are being run and more (specifically which messages are reported depends on log level threshold selected by the user). |
79 | /// All these messages constitute Unit Test Framework log. There are many ways (formats) to present these messages to the user. Boost.Test comes with |
80 | /// two formats: "Compiler-like log format" and "XML based log format". Former is intended for human consumption and later is intended for processing |
81 | /// by automated regression test systems. If you want to produce some other format you need to implement class with specific interface and use |
82 | /// method unit_test_log_t::set_formatter during a test module initialization to set an active formatter. The class unit_test_log_formatter defines this |
83 | /// interface. |
84 | /// |
85 | /// This interface requires you to format all possible messages being produced in the log. These includes error messages about failed assertions, messages |
86 | /// about caught exceptions and information messages about test units being started/ended. All the methods in this interface takes a reference to standard |
87 | /// stream as a first argument. This is where final messages needs to be directed to. Also you are given all the information necessary to produce a message. |
88 | class BOOST_TEST_DECL unit_test_log_formatter { |
89 | public: |
90 | /// Types of log entries (messages written into a log) |
91 | enum log_entry_types { BOOST_UTL_ET_INFO, ///< Information message from the framework |
92 | BOOST_UTL_ET_MESSAGE, ///< Information message from the user |
93 | BOOST_UTL_ET_WARNING, ///< Warning (non error) condition notification message |
94 | BOOST_UTL_ET_ERROR, ///< Non fatal error notification message |
95 | BOOST_UTL_ET_FATAL_ERROR ///< Fatal error notification message |
96 | }; |
97 | |
98 | // Destructor |
99 | virtual ~unit_test_log_formatter() {} |
100 | |
101 | // @name Test start/finish |
102 | |
103 | /// Invoked at the beginning of test module execution |
104 | |
105 | /// @param[in] os output stream to write a messages to |
106 | /// @param[in] test_cases_amount total test case amount to be run |
107 | /// @see log_finish |
108 | virtual void log_start( std::ostream& os, counter_t test_cases_amount ) = 0; |
109 | |
110 | /// Invoked at the end of test module execution |
111 | |
112 | /// @param[in] os output stream to write a messages into |
113 | /// @see log_start |
114 | virtual void log_finish( std::ostream& os ) = 0; |
115 | |
116 | /// Invoked when Unit Test Framework build information is requested |
117 | |
118 | /// @param[in] os output stream to write a messages into |
119 | virtual void log_build_info( std::ostream& os ) = 0; |
120 | // @} |
121 | |
122 | // @name Test unit start/finish |
123 | |
124 | /// Invoked when test unit starts (either test suite or test case) |
125 | |
126 | /// @param[in] os output stream to write a messages into |
127 | /// @param[in] tu test unit being started |
128 | /// @see test_unit_finish |
129 | virtual void test_unit_start( std::ostream& os, test_unit const& tu ) = 0; |
130 | |
131 | /// Invoked when test unit finishes |
132 | |
133 | /// @param[in] os output stream to write a messages into |
134 | /// @param[in] tu test unit being finished |
135 | /// @param[in] elapsed time in milliseconds spend executing this test unit |
136 | /// @see test_unit_start |
137 | virtual void test_unit_finish( std::ostream& os, test_unit const& tu, unsigned long elapsed ) = 0; |
138 | |
139 | /// Invoked if test unit skipped for any reason |
140 | |
141 | /// @param[in] os output stream to write a messages into |
142 | /// @param[in] tu skipped test unit |
143 | /// @param[in] reason explanation why was it skipped |
144 | virtual void test_unit_skipped( std::ostream& os, test_unit const& tu, const_string reason ) |
145 | { |
146 | test_unit_skipped( os, tu ); |
147 | } |
148 | |
149 | /// Deprecated version of this interface |
150 | virtual void test_unit_skipped( std::ostream& os, test_unit const& tu ) {} |
151 | |
152 | // @} |
153 | |
154 | // @name Uncaught exception report |
155 | |
156 | /// Invoked when Unit Test Framework detects uncaught exception |
157 | |
158 | /// Call to this function starts uncaught exception report. It is going to followed by context information. Report is finalized by call to |
159 | /// log_exception_finish. |
160 | /// @param[in] os output stream to write a messages into |
161 | /// @param[in] lcd information about the last checkpoint before the exception was triggered |
162 | /// @param[in] ex information about the caught exception |
163 | /// @see log_exception_finish |
164 | virtual void log_exception_start( std::ostream& os, log_checkpoint_data const& lcd, execution_exception const& ex ) = 0; |
165 | |
166 | /// Invoked when Unit Test Framework detects uncaught exception |
167 | |
168 | /// Call to this function finishes uncaught exception report. |
169 | /// @param[in] os output stream to write a messages into |
170 | /// @see log_exception_start |
171 | virtual void log_exception_finish( std::ostream& os ) = 0; |
172 | // @} |
173 | |
174 | // @name Regular log entry |
175 | |
176 | /// Invoked by Unit Test Framework to start new log entry |
177 | |
178 | /// Call to this function starts new log entry. It is followed by series of log_entry_value calls and finally call to log_entry_finish. |
179 | /// A log entry may consist of one or more values being reported. Some of these values will be plain strings, while others can be complicated |
180 | /// expressions in a form of "lazy" expression template lazy_ostream. |
181 | /// @param[in] os output stream to write a messages into |
182 | /// @param[in] led log entry attributes |
183 | /// @param[in] let log entry type log_entry_finish |
184 | /// @see log_entry_value, log_entry_finish |
185 | virtual void log_entry_start( std::ostream& os, log_entry_data const& led, log_entry_types let ) = 0; |
186 | |
187 | /// Invoked by Unit Test Framework to report a log entry content |
188 | |
189 | /// This is one of two overloaded methods to report log entry content. This one is used to report plain string value. |
190 | /// @param[in] os output stream to write a messages into. |
191 | /// @param[in] value log entry string value |
192 | /// @see log_entry_start, log_entry_finish |
193 | virtual void log_entry_value( std::ostream& os, const_string value ) = 0; |
194 | |
195 | /// Invoked by Unit Test Framework to report a log entry content |
196 | |
197 | /// This is one of two overloaded methods to report log entry content. This one is used to report some complicated expression passed as |
198 | /// an expression template lazy_ostream. In most cases default implementation provided by the framework should work as is (it just converts |
199 | /// the lazy expression into a string. |
200 | /// @param[in] os output stream to write a messages into |
201 | /// @param[in] value log entry "lazy" value |
202 | /// @see log_entry_start, log_entry_finish |
203 | virtual void log_entry_value( std::ostream& os, lazy_ostream const& value ); // there is a default impl |
204 | |
205 | /// Invoked by Unit Test Framework to finish a log entry report |
206 | |
207 | /// @param[in] os output stream to write a messages into |
208 | /// @see log_entry_start, log_entry_start |
209 | virtual void log_entry_finish( std::ostream& os ) = 0; |
210 | // @} |
211 | |
212 | // @name Log entry context report |
213 | |
214 | /// Invoked by Unit Test Framework to start log entry context report |
215 | |
216 | /// Unit Test Framework logs for failed assertions and uncaught exceptions context if one was defined by a test module. |
217 | /// Context consists of multiple "scopes" identified by description messages assigned by the test module using |
218 | /// BOOST_TEST_INFO/BOOST_TEST_CONTEXT statements. |
219 | /// @param[in] os output stream to write a messages into |
220 | /// @param[in] l entry log_leveg, to be used to fine tune the message |
221 | /// @see log_entry_context, entry_context_finish |
222 | virtual void entry_context_start( std::ostream& os, log_level l ) = 0; |
223 | |
224 | /// Invoked by Unit Test Framework to report log entry context "scope" description |
225 | |
226 | /// Each "scope" description is reported by separate call to log_entry_context. |
227 | /// @param[in] os output stream to write a messages into |
228 | /// @param[in] value context "scope" description |
229 | /// @see log_entry_start, entry_context_finish |
230 | virtual void log_entry_context( std::ostream& os, const_string value ) = 0; |
231 | |
232 | /// Invoked by Unit Test Framework to finish log entry context report |
233 | |
234 | /// @param[in] os output stream to write a messages into |
235 | /// @see log_entry_start, entry_context_context |
236 | virtual void entry_context_finish( std::ostream& os ) = 0; |
237 | // @} |
238 | }; |
239 | |
240 | } // namespace unit_test |
241 | } // namespace boost |
242 | |
243 | //____________________________________________________________________________// |
244 | |
245 | #include <boost/test/detail/enable_warnings.hpp> |
246 | |
247 | #endif // BOOST_TEST_UNIT_TEST_LOG_FORMATTER_HPP_071894GER |
248 | |
249 | |