...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
boost::unit_test::unit_test_log_t — Manages the sets of loggers, their streams and log levels.
// In header: <boost/test/unit_test_log.hpp> class unit_test_log_t : public boost::unit_test::test_observer { public: // public member functions virtual void test_start(counter_t, test_unit_id); virtual void test_finish(); virtual void test_aborted(); virtual void test_unit_start(test_unit const &); virtual void test_unit_finish(test_unit const &, unsigned long); virtual void test_unit_skipped(test_unit const &, const_string); virtual void test_unit_aborted(test_unit const &); virtual void test_unit_timed_out(test_unit const &); virtual void exception_caught(execution_exception const &); virtual int priority(); void set_stream(std::ostream &); void set_stream(output_format, std::ostream &); std::ostream * get_stream(output_format) const; log_level set_threshold_level(log_level); log_level set_threshold_level(output_format, log_level); void add_format(output_format); void set_format(output_format); unit_test_log_formatter * get_formatter(output_format); void set_formatter(unit_test_log_formatter *); void add_formatter(unit_test_log_formatter *); void set_checkpoint(const_string, std::size_t, const_string = const_string()); unit_test_log_t & operator<<(log::begin const &); unit_test_log_t & operator<<(log::end const &); unit_test_log_t & operator<<(log_level); unit_test_log_t & operator<<(const_string); unit_test_log_t & operator<<(lazy_ostream const &); unspecified operator()(log_level); void configure(); virtual void test_unit_skipped(test_unit const &); virtual void assertion_result(unit_test::assertion_result); };
The Boost.Test framework allows for having several formatters/loggers at the same time, each of which having their own log level and output stream.
This class serves the purpose of
exposing an interface to the test framework (as a boost::unit_test::test_observer)
exposing an interface to the testing tools
managing several loggers
Note | |
---|---|
Accesses to the functions exposed by this class are made through the singleton |
Users/developers willing to implement their own formatter need to:
implement a boost::unit_test::unit_test_log_formatter that will output the desired format
register the formatter during a eg. global fixture using the method set_formatter
(though the framework singleton).
Warning | |
---|---|
this observer has a higher priority than the boost::unit_test::results_collector_t. This means that the various boost::unit_test::test_results associated to each test unit may not be available at the time the |
See Also:
unit_test_log_t
public member functionsvirtual void test_start(counter_t, test_unit_id);Called before the framework starts executing the test cases.
virtual void test_finish();Called after the framework ends executing the test cases.
Note | |
---|---|
The call is made with a reversed priority order. |
virtual void test_aborted();Called when a critical error is detected.
The critical errors are mainly the signals sent by the system and caught by the Boost.Test framework. Since the running binary may be in incoherent/instable state, the test execution is aborted and all remaining tests are discarded.
Note | |
---|---|
may be called before test_observer::test_unit_finish() |
virtual void test_unit_start(test_unit const &);Called before the framework starts executing a test unit.
virtual void test_unit_finish(test_unit const &, unsigned long);Called at each end of a test unit.
virtual void test_unit_skipped(test_unit const &, const_string);
virtual void test_unit_aborted(test_unit const &);Called when a test unit indicates a fatal error.
A fatal error happens when
a strong assertion (with REQUIRE
) fails, which indicates that the test case cannot continue
an unexpected exception is caught by the Boost.Test framework
virtual void test_unit_timed_out(test_unit const &);Called when the test timed out.
This function is called to signal that a test unit (case or suite) timed out. A valid test unit is available through boost::unit_test::framework::current_test_unit
virtual void exception_caught(execution_exception const &);Called when an exception is intercepted.
In case an exception is intercepted, this call happens before the call to test_unit_aborted in order to log additional data about the exception.
virtual int priority();The priority indicates the order at which this observer is initialized and tore down in the UTF framework. The order is lowest to highest priority.
void set_stream(std::ostream &);Sets the stream for all loggers.
This will override the log sink/stream of all loggers, whether enabled or not.
void set_stream(output_format, std::ostream &);Sets the stream for specific logger.
Note | |
---|---|
Has no effect if the specified format is not found |
Since Boost 1.62.
std::ostream * get_stream(output_format) const;Returns a pointer to the stream associated to specific logger.
Note | |
---|---|
Returns a null pointer if the format is not found |
Since Boost 1.67.
log_level set_threshold_level(log_level);Sets the threshold level for all loggers/formatters.
This will override the log level of all loggers, whether enabled or not.
Returns: |
the minimum of the previous log level of all formatters (new in Boost 1.73) |
log_level set_threshold_level(output_format, log_level);Sets the threshold/log level of a specific format.
Note | |
---|---|
Has no effect if the specified format is not found |
Since Boost 1.62.
Returns: |
the previous log level of the corresponding formatter (new in Boost 1.73) |
void add_format(output_format);Add a format to the set of loggers.
Adding a logger means that the specified logger is enabled. The log level is managed by the formatter itself and specifies what events are forwarded to the underlying formatter.
Since Boost 1.62.
void set_format(output_format);Sets the format of the logger.
This will become the only active format of the logs.
unit_test_log_formatter * get_formatter(output_format);Returns the logger instance for a specific format.
Since Boost 1.62.
Returns: |
the logger/formatter instance, or |
void set_formatter(unit_test_log_formatter *);Sets the logger instance.
The specified logger becomes the unique active one. The custom log formatter has the format OF_CUSTOM_LOGGER
. If such a format exists already, its formatter gets replaced by the one given in argument.
The log level and output stream of the new formatter are taken from the currently active logger. In case several loggers are active, the order of priority is CUSTOM, HRF, XML, and JUNIT. If (unit_test_log_formatter*)0 is given as argument, the custom logger (if any) is removed.
Note | |
---|---|
The ownership of the pointer is transferred to the Boost.Test framework. This call is equivalent to
|
void add_formatter(unit_test_log_formatter * the_formatter);Adds a custom log formatter to the set of formatters.
The specified logger is added with the format OF_CUSTOM_LOGGER
, such that it can be futher selected or its stream/log level can be specified. If there is already a custom logger (with OF_CUSTOM_LOGGER
), then the existing one gets replaced by the one given in argument. The provided logger is added with an enabled state. If (unit_test_log_formatter*)0 is given as argument, the custom logger (if any) is removed and no other action is performed.
Note | |
---|---|
The ownership of the pointer is transferred to the Boost.Test framework. |
Since Boost 1.62.
void set_checkpoint(const_string file, std::size_t line_num, const_string msg = const_string());
unit_test_log_t & operator<<(log::begin const &);
unit_test_log_t & operator<<(log::end const &);
unit_test_log_t & operator<<(log_level);
unit_test_log_t & operator<<(const_string);
unit_test_log_t & operator<<(lazy_ostream const &);
unspecified operator()(log_level);
void configure();Prepares internal states after log levels, streams and format has been set up.
virtual void test_unit_skipped(test_unit const &);backward compatibility
virtual void assertion_result(unit_test::assertion_result);