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
31namespace boost {
32namespace unit_test {
33
34// ************************************************************************** //
35/// Collection of log entry attributes
36// ************************************************************************** //
37
38struct 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
60struct 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.
88class BOOST_TEST_DECL unit_test_log_formatter {
89public:
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

source code of boost/boost/test/unit_test_log_formatter.hpp