boost/test/unit_test_log.hpp

   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 singleton class unit_test_log and all manipulators.
  10 /// unit_test_log has output stream like interface. It's implementation is
  11 /// completely hidden with pimple idiom
  12 // ***************************************************************************
  13
  14 #ifndef BOOST_TEST_UNIT_TEST_LOG_HPP_071894GER
  15 #define BOOST_TEST_UNIT_TEST_LOG_HPP_071894GER
  16
  17 // Boost.Test
  18 #include <boost/test/tree/observer.hpp>
  19
  20 #include <boost/test/detail/global_typedef.hpp>
  21 #include <boost/test/detail/log_level.hpp>
  22 #include <boost/test/detail/fwd_decl.hpp>
  23
  24 #include <boost/test/utils/wrap_stringstream.hpp>
  25 #include <boost/test/utils/lazy_ostream.hpp>
  26
  27 // Boost
  28
  29 // STL
  30 #include <iosfwd>   // for std::ostream&
  31
  32 #include <boost/test/detail/suppress_warnings.hpp>
  33
  34 //____________________________________________________________________________//
  35
  36 namespace boost {
  37 namespace unit_test {
  38
  39 // ************************************************************************** //
  40 // **************                log manipulators              ************** //
  41 // ************************************************************************** //
  42
  43 namespace log {
  44
  45 struct BOOST_TEST_DECL begin {
  46     begin( const_string fn, std::size_t ln )
  47     : m_file_name( fn )
  48     , m_line_num( ln )
  49     {}
  50
  51     const_string m_file_name;
  52     std::size_t m_line_num;
  53 };
  54
  55 struct end {};
  56
  57 } // namespace log
  58
  59 // ************************************************************************** //
  60 // **************             entry_value_collector            ************** //
  61 // ************************************************************************** //
  62
  63 namespace ut_detail {
  64
  65 class BOOST_TEST_DECL entry_value_collector {
  66 public:
  67     // Constructors
  68     entry_value_collector() : m_last( true ) {}
  69     entry_value_collector( entry_value_collector const& rhs ) : m_last( true ) { rhs.m_last = false; }
  70     ~entry_value_collector();
  71
  72     // collection interface
  73     entry_value_collector const& operator<<( lazy_ostream const& ) const;
  74     entry_value_collector const& operator<<( const_string ) const;
  75
  76 private:
  77     // Data members
  78     mutable bool    m_last;
  79 };
  80
  81 } // namespace ut_detail
  82
  83 // ************************************************************************** //
  84 // **************                 unit_test_log                ************** //
  85 // ************************************************************************** //
  86
  87 /// @brief Manages the sets of loggers, their streams and log levels
  88 ///
  89 /// The Boost.Test framework allows for having several formatters/loggers at the same time, each of which
  90 /// having their own log level and output stream.
  91 ///
  92 /// This class serves the purpose of
  93 /// - exposing an interface to the test framework (as a boost::unit_test::test_observer)
  94 /// - exposing an interface to the testing tools
  95 /// - managing several loggers
  96 ///
  97 /// @note Accesses to the functions exposed by this class are made through the singleton
  98 ///   @c boost::unit_test::unit_test_log.
  99 ///
 100 /// Users/developers willing to implement their own formatter need to:
 101 /// - implement a boost::unit_test::unit_test_log_formatter that will output the desired format
 102 /// - register the formatter during a eg. global fixture using the method @c set_formatter (though the framework singleton).
 103 ///
 104 /// @warning this observer has a higher priority than the @ref boost::unit_test::results_collector_t. This means
 105 /// that the various @ref boost::unit_test::test_results associated to each test unit may not be available at the time
 106 /// the @c test_unit_start, @c test_unit_finish ... are called.
 107 ///
 108 /// @see
 109 /// - boost::unit_test::test_observer
 110 /// - boost::unit_test::unit_test_log_formatter
 111 class BOOST_TEST_DECL unit_test_log_t : public test_observer {
 112 public:
 113     // test_observer interface implementation
 114     virtual void        test_start( counter_t test_cases_amount );
 115     virtual void        test_finish();
 116     virtual void        test_aborted();
 117
 118     virtual void        test_unit_start( test_unit const& );
 119     virtual void        test_unit_finish( test_unit const&, unsigned long elapsed );
 120     virtual void        test_unit_skipped( test_unit const&, const_string );
 121     virtual void        test_unit_aborted( test_unit const& );
 122     virtual void        test_unit_timed_out( test_unit const& );
 123
 124     virtual void        exception_caught( execution_exception const& ex );
 125
 126     virtual int         priority() { return 2; }
 127
 128     // log configuration methods
 129     //! Sets the stream for all loggers
 130     //!
 131     //! This will override the log sink/stream of all loggers, whether enabled or not.
 132     void                set_stream( std::ostream& );
 133
 134     //! Sets the stream for specific logger
 135     //!
 136     //! @note Has no effect if the specified format is not found
 137     //! @par Since Boost 1.62
 138     void                set_stream( output_format, std::ostream& );
 139
 140     //! Returns a pointer to the stream associated to specific logger
 141     //!
 142     //! @note Returns a null pointer if the format is not found
 143     //! @par Since Boost 1.67
 144     std::ostream*       get_stream( output_format ) const;
 145
 146
 147     //! Sets the threshold level for all loggers/formatters.
 148     //!
 149     //! This will override the log level of all loggers, whether enabled or not.
 150     void                set_threshold_level( log_level );
 151
 152     //! Sets the threshold/log level of a specific format
 153     //!
 154     //! @note Has no effect if the specified format is not found
 155     //! @par Since Boost 1.62
 156     void                set_threshold_level( output_format, log_level );
 157
 158     //! Add a format to the set of loggers
 159     //!
 160     //! Adding a logger means that the specified logger is enabled. The log level is managed by the formatter itself
 161     //! and specifies what events are forwarded to the underlying formatter.
 162     //! @par Since Boost 1.62
 163     void                add_format( output_format );
 164
 165     //! Sets the format of the logger
 166     //!
 167     //! This will become the only active format of the logs.
 168     void                set_format( output_format );
 169
 170     //! Returns the logger instance for a specific format.
 171     //!
 172     //! @returns the logger/formatter instance, or @c (unit_test_log_formatter*)0 if the format is not found.
 173     //! @par Since Boost 1.62
 174     unit_test_log_formatter* get_formatter( output_format );
 175
 176     //! Sets the logger instance
 177     //!
 178     //! The specified logger becomes the unique active one. The custom log formatter has the
 179     //! format @c OF_CUSTOM_LOGGER. If such a format exists already, its formatter gets replaced by the one
 180     //! given in argument.
 181     //!
 182     //! The log level and output stream of the new formatter are taken from the currently active logger. In case
 183     //! several loggers are active, the order of priority is CUSTOM, HRF, XML, and JUNIT.
 184     //! If (unit_test_log_formatter*)0 is given as argument, the custom logger (if any) is removed.
 185     //!
 186     //! @note The ownership of the pointer is transfered to the Boost.Test framework. This call is equivalent to
 187     //! - a call to @c add_formatter
 188     //! - a call to @c set_format(OF_CUSTOM_LOGGER)
 189     //! - a configuration of the newly added logger with a previously configured stream and log level.
 190     void                set_formatter( unit_test_log_formatter* );
 191
 192     //! Adds a custom log formatter to the set of formatters
 193     //!
 194     //! The specified logger is added with the format @c OF_CUSTOM_LOGGER, such that it can
 195     //! be futher selected or its stream/log level can be specified.
 196     //! If there is already a custom logger (with @c OF_CUSTOM_LOGGER), then
 197     //! the existing one gets replaced by the one given in argument.
 198     //! The provided logger is added with an enabled state.
 199     //! If (unit_test_log_formatter*)0 is given as argument, the custom logger (if any) is removed and
 200     //! no other action is performed.
 201     //!
 202     //! @note The ownership of the pointer is transfered to the Boost.Test framework.
 203     //! @par Since Boost 1.62
 204     void                add_formatter( unit_test_log_formatter* the_formatter );
 205
 206     // test progress logging
 207     void                set_checkpoint( const_string file, std::size_t line_num, const_string msg = const_string() );
 208
 209     // entry logging
 210     unit_test_log_t&    operator<<( log::begin const& );        // begin entry
 211     unit_test_log_t&    operator<<( log::end const& );          // end entry
 212     unit_test_log_t&    operator<<( log_level );                // set entry level
 213     unit_test_log_t&    operator<<( const_string );             // log entry value
 214     unit_test_log_t&    operator<<( lazy_ostream const& );      // log entry value
 215
 216     ut_detail::entry_value_collector operator()( log_level );   // initiate entry collection
 217
 218 private:
 219     // Implementation helpers
 220     bool                log_entry_start(output_format log_format);
 221     void                log_entry_context( log_level l );
 222     void                clear_entry_context();
 223
 224     // Singleton
 225     BOOST_TEST_SINGLETON_CONS( unit_test_log_t )
 226 }; // unit_test_log_t
 227
 228 BOOST_TEST_SINGLETON_INST( unit_test_log )
 229
 230 // helper macros
 231 #define BOOST_TEST_LOG_ENTRY( ll )                                                  \
 232     (::boost::unit_test::unit_test_log                                              \
 233         << ::boost::unit_test::log::begin( BOOST_TEST_L(__FILE__), __LINE__ ))(ll)  \
 234 /**/
 235
 236 } // namespace unit_test
 237 } // namespace boost
 238
 239 // ************************************************************************** //
 240 // **************       Unit test log interface helpers        ************** //
 241 // ************************************************************************** //
 242
 243 // messages sent by the framework
 244 #define BOOST_TEST_FRAMEWORK_MESSAGE( M )                       \
 245    (::boost::unit_test::unit_test_log                           \
 246         << ::boost::unit_test::log::begin(                      \
 247                 "boost.test framework",                         \
 248                 0 ))                                     \
 249              ( ::boost::unit_test::log_messages )               \
 250     << BOOST_TEST_LAZY_MSG( M )                                 \
 251 /**/
 252
 253
 254 #define BOOST_TEST_MESSAGE( M )                                 \
 255     BOOST_TEST_LOG_ENTRY( ::boost::unit_test::log_messages )    \
 256     << BOOST_TEST_LAZY_MSG( M )                                 \
 257 /**/
 258
 259 //____________________________________________________________________________//
 260
 261 #define BOOST_TEST_PASSPOINT()                                  \
 262     ::boost::unit_test::unit_test_log.set_checkpoint(           \
 263         BOOST_TEST_L(__FILE__),                                 \
 264         static_cast<std::size_t>(__LINE__) )                    \
 265 /**/
 266
 267 //____________________________________________________________________________//
 268
 269 #define BOOST_TEST_CHECKPOINT( M )                              \
 270     ::boost::unit_test::unit_test_log.set_checkpoint(           \
 271         BOOST_TEST_L(__FILE__),                                 \
 272         static_cast<std::size_t>(__LINE__),                     \
 273         (::boost::wrap_stringstream().ref() << M).str() )       \
 274 /**/
 275
 276 //____________________________________________________________________________//
 277
 278 #include <boost/test/detail/enable_warnings.hpp>
 279
 280 #endif // BOOST_TEST_UNIT_TEST_LOG_HPP_071894GER
 281