Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Class unit_test_log_t

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 singleton< unit_test_log_t >

  // public member functions
  virtual void test_start(counter_t);
  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 exception_caught(execution_exception const &);
  virtual int priority();
  void set_stream(std::ostream &);
  void set_stream(output_format, std::ostream &);
  void set_threshold_level(log_level);
  void 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);
  virtual void test_unit_skipped(test_unit const &);
  virtual void assertion_result(unit_test::assertion_result);

  // private member functions
  bool log_entry_start(output_format);
  void log_entry_context(log_level);
  void clear_entry_context();

  // protected member functions
  virtual void assertion_result(bool);


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

[Note] Note

Accesses to the functions exposed by this class are made through the singleton boost::unit_test::unit_test_log.

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] 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 test_unit_start, test_unit_finish ... are called.

See Also:

unit_test_log_t public member functions

  1. virtual void test_start(counter_t);
    Called before the framework starts executing the test cases.

  2. virtual void test_finish();
    Called after the framework ends executing the test cases.
    [Note] Note

    The call is made with a reversed priority order.

  3. 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] Note

    may be called before test_observer::test_unit_finish()

  4. virtual void test_unit_start(test_unit const &);
    Called before the framework starts executing a test unit.

  5. virtual void test_unit_finish(test_unit const &, unsigned long long);
    Called at each end of a test unit.

  6. virtual void test_unit_skipped(test_unit const &, const_string);
  7. 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

  8. 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.

  9. 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.
  10. 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.

  11. void set_stream(output_format, std::ostream &);
    Sets the stream for specific logger.
    [Note] Note

    Has no effect if the specified format is not found

    Since Boost 1.62 . 

  12. void 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.

  13. void set_threshold_level(output_format, log_level);
    Sets the threshold/log level of a specific format.
    [Note] Note

    Has no effect if the specified format is not found

    Since Boost 1.62 . 

  14. 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 . 

  15. void set_format(output_format);
    Sets the format of the logger.

    This will become the only active format of the logs.

  16. unit_test_log_formatter * get_formatter(output_format);
    Returns the logger instance for a specific format.

    Since Boost 1.62 . 


    the logger/formatter instance, or (unit_test_log_formatter*)0 if the format is not found.

  17. 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] Note

    The ownership of the pointer is transfered to the Boost.Test framework. This call is equivalent to

    • a call to add_formatter

    • a call to set_format(OF_CUSTOM_LOGGER)

    • a configuration of the newly added logger with a previously configured stream and log level.

  18. 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] Note

    The ownership of the pointer is transfered to the Boost.Test framework.

    Since Boost 1.62 . 

  19. void set_checkpoint(const_string file, std::size_t line_num, 
                        const_string msg = const_string());
  20. unit_test_log_t & operator<<(log::begin const &);
  21. unit_test_log_t & operator<<(log::end const &);
  22. unit_test_log_t & operator<<(log_level);
  23. unit_test_log_t & operator<<(const_string);
  24. unit_test_log_t & operator<<(lazy_ostream const &);
  25. unspecified operator()(log_level);
  26. virtual void test_unit_skipped(test_unit const &);
    backward compatibility
  27. virtual void assertion_result(unit_test::assertion_result ar);

unit_test_log_t private member functions

  1. bool log_entry_start(output_format log_format);
  2. void log_entry_context(log_level l);
  3. void clear_entry_context();

unit_test_log_t protected member functions

  1. virtual void assertion_result(bool);