1 // (C) Copyright Gennadiy Rozental 2003-2014. 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 { log_entry_databoost::unit_test::log_entry_data39 log_entry_data() 40 { 41 m_file_name.reserve( 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 clearboost::unit_test::log_entry_data48 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 clearboost::unit_test::log_checkpoint_data66 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 ~unit_test_log_formatter()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 test_unit_skipped(std::ostream & os,test_unit const & tu,const_string reason)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 test_unit_skipped(std::ostream & os,test_unit const & tu)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