Boost C++ Libraries

...one 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.
PrevUpHomeNext

Class unit_test_log_formatter

boost::unit_test::unit_test_log_formatter — Abstract Unit Test Framework log formatter interface.

Synopsis

// In header: <boost/test/unit_test_log_formatter.hpp>


class unit_test_log_formatter {
public:

  // Types of log entries (messages written into a log) 
  enum log_entry_types { BOOST_UTL_ET_INFO, BOOST_UTL_ET_MESSAGE, 
                         BOOST_UTL_ET_WARNING, BOOST_UTL_ET_ERROR, 
                         BOOST_UTL_ET_FATAL_ERROR };
  // construct/copy/destruct
  unit_test_log_formatter();
  ~unit_test_log_formatter();

  // public member functions
  virtual void log_start(std::ostream &, counter_t) = 0;
  virtual void log_finish(std::ostream &) = 0;
  virtual void log_build_info(std::ostream &, bool = true) = 0;
  virtual void test_unit_start(std::ostream &, test_unit const &) = 0;
  virtual void 
  test_unit_finish(std::ostream &, test_unit const &, unsigned long) = 0;
  virtual void 
  test_unit_skipped(std::ostream &, test_unit const &, const_string);
  virtual void test_unit_skipped(std::ostream &, test_unit const &);
  virtual void test_unit_aborted(std::ostream &, test_unit const &);
  virtual void test_unit_timed_out(std::ostream &, test_unit const &);
  virtual void 
  log_exception_start(std::ostream &, log_checkpoint_data const &, 
                      execution_exception const &) = 0;
  virtual void log_exception_finish(std::ostream &) = 0;
  virtual void 
  log_entry_start(std::ostream &, log_entry_data const &, log_entry_types) = 0;
  virtual void log_entry_value(std::ostream &, const_string) = 0;
  virtual void log_entry_value(std::ostream &, lazy_ostream const &);
  virtual void log_entry_finish(std::ostream &) = 0;
  virtual void entry_context_start(std::ostream &, log_level) = 0;
  virtual void log_entry_context(std::ostream &, log_level, const_string) = 0;
  virtual void entry_context_finish(std::ostream &, log_level) = 0;
  virtual void set_log_level(log_level);
  virtual log_level get_log_level() const;
  virtual std::string get_default_stream_description() const;
};

Description

During the test module execution Unit Test Framework can report messages about success or failure of assertions, which test suites are being run and more (specifically which messages are reported depends on log level threshold selected by the user).

All these messages constitute Unit Test Framework log. There are many ways (formats) to present these messages to the user.

Boost.Test comes with three formats:

  • Compiler-like log format: intended for human consumption/diagnostic

  • XML based log format: intended for processing by automated regression test systems.

  • JUNIT based log format: intended for processing by automated regression test systems.

If you want to produce some other format you need to implement class with specific interface and use 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 interface.

This interface requires you to format all possible messages being produced in the log. These includes error messages about failed assertions, messages about caught exceptions and information messages about test units being started/ended. All the methods in this interface takes a reference to standard 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.

Since Boost 1.62: 

  • Each formatter may indicate the default output stream. This is convenient for instance for streams intended for automated processing that indicate a file. See get_default_stream_description for more details.

  • Each formatter may manage its own log level through the getter/setter get_log_level and set_log_level .

See Also:

unit_test_log_formatter public construct/copy/destruct

  1. unit_test_log_formatter();
    Constructor.
  2. ~unit_test_log_formatter();

unit_test_log_formatter public member functions

  1. virtual void log_start(std::ostream & os, counter_t test_cases_amount) = 0;
    Invoked at the beginning of test module execution.

    See Also:

    log_finish

    Parameters:

    os

    output stream to write a messages to

    test_cases_amount

    total test case amount to be run

  2. virtual void log_finish(std::ostream & os) = 0;
    Invoked at the end of test module execution.

    See Also:

    log_start

    Parameters:

    os

    output stream to write a messages into

  3. virtual void log_build_info(std::ostream & os, bool log_build_info = true) = 0;
    Invoked when Unit Test Framework build information is requested.

    Parameters:

    log_build_info

    indicates if build info should be logged or not

    os

    output stream to write a messages into

  4. virtual void test_unit_start(std::ostream & os, test_unit const & tu) = 0;
    Invoked when test unit starts (either test suite or test case)

    See Also:

    test_unit_finish

    Parameters:

    os

    output stream to write a messages into

    tu

    test unit being started

  5. virtual void 
    test_unit_finish(std::ostream & os, test_unit const & tu, 
                     unsigned long elapsed) = 0;
    Invoked when test unit finishes.

    See Also:

    test_unit_start

    Parameters:

    elapsed

    time in microseconds spend executing this test unit

    os

    output stream to write a messages into

    tu

    test unit being finished

  6. virtual void 
    test_unit_skipped(std::ostream & os, test_unit const & tu, const_string);
    Invoked if test unit skipped for any reason.

    Parameters:

    os

    output stream to write a messages into

    tu

    skipped test unit

  7. virtual void test_unit_skipped(std::ostream &, test_unit const &);
    Deprecated version of this interface.

    <xrefsect><xreftitle>Deprecated</xreftitle><xrefdescription></xrefdescription></xrefsect>

  8. virtual void test_unit_aborted(std::ostream &, test_unit const &);
    Invoked when a test unit is aborted.
  9. virtual void test_unit_timed_out(std::ostream &, test_unit const &);
    Invoked when a test unit times-out.
  10. virtual void 
    log_exception_start(std::ostream & os, log_checkpoint_data const & lcd, 
                        execution_exception const & ex) = 0;
    Invoked when Unit Test Framework detects uncaught exception.

    The framwork calls this function when an uncaught exception it detected. This call is followed by context information:

    • one call to entry_context_start,

    • as many calls to log_entry_context as there are context entries

    • one call to entry_context_finish

    The logging of the exception information is finilized by a call to log_exception_finish.

    See Also:

    log_exception_finish

    Parameters:

    ex

    information about the caught exception

    lcd

    information about the last checkpoint before the exception was triggered

    os

    output stream to write a messages into

  11. virtual void log_exception_finish(std::ostream & os) = 0;
    Invoked when Unit Test Framework detects uncaught exception.

    Call to this function finishes uncaught exception report.

    See Also:

    log_exception_start

    Parameters:

    os

    output stream to write a messages into

  12. virtual void 
    log_entry_start(std::ostream & os, log_entry_data const & led, 
                    log_entry_types let) = 0;
    Invoked by Unit Test Framework to start new log entry.

    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. 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 expressions in a form of "lazy" expression template lazy_ostream.

    See Also:

    log_entry_value, log_entry_finish

    [Note] Note

    call to this function may happen before any call to test_unit_start or all calls to test_unit_finish as the framework might log errors raised during global initialization/shutdown.

    Parameters:

    led

    log entry attributes

    let

    log entry type log_entry_finish

    os

    output stream to write a messages into

  13. virtual void log_entry_value(std::ostream & os, const_string value) = 0;
    Invoked by Unit Test Framework to report a log entry content.

    This is one of two overloaded methods to report log entry content. This one is used to report plain string value.

    See Also:

    log_entry_start, log_entry_finish

    Parameters:

    os

    output stream to write a messages into.

    value

    log entry string value

  14. virtual void log_entry_value(std::ostream & os, lazy_ostream const & value);
    Invoked by Unit Test Framework to report a log entry content.

    This is one of two overloaded methods to report log entry content. This one is used to report some complicated expression passed as an expression template lazy_ostream. In most cases default implementation provided by the framework should work as is (it just converts the lazy expression into a string.

    See Also:

    log_entry_start, log_entry_finish

    Parameters:

    os

    output stream to write a messages into

    value

    log entry "lazy" value

  15. virtual void log_entry_finish(std::ostream & os) = 0;
    Invoked by Unit Test Framework to finish a log entry report.

    See Also:

    log_entry_start, log_entry_start

    Parameters:

    os

    output stream to write a messages into

  16. virtual void entry_context_start(std::ostream & os, log_level l) = 0;
    Invoked by Unit Test Framework to start log entry context report.

    Unit Test Framework logs for failed assertions and uncaught exceptions context if one was defined by a test module. Context consists of multiple "scopes" identified by description messages assigned by the test module using BOOST_TEST_INFO/BOOST_TEST_CONTEXT statements.

    See Also:

    log_entry_context, entry_context_finish

    Parameters:

    l

    entry log_level, to be used to fine tune the message

    os

    output stream to write a messages into

  17. virtual void 
    log_entry_context(std::ostream & os, log_level l, const_string value) = 0;
    Invoked by Unit Test Framework to report log entry context "scope" description.

    Each "scope" description is reported by separate call to log_entry_context.

    See Also:

    log_entry_start, entry_context_finish

    Parameters:

    l

    entry log_level, to be used to fine tune the message

    os

    output stream to write a messages into

    value

    context "scope" description

  18. virtual void entry_context_finish(std::ostream & os, log_level l) = 0;
    Invoked by Unit Test Framework to finish log entry context report.

    See Also:

    log_entry_start, entry_context_context

    Parameters:

    l

    entry log_level, to be used to fine tune the message

    os

    output stream to write a messages into

  19. virtual void set_log_level(log_level new_log_level);
    Sets the log level of the logger/formatter.

    Some loggers need to manage the log level by their own. This member function let the implementation decide of that.

    Since Boost 1.62. 

  20. virtual log_level get_log_level() const;
    Returns the log level of the logger/formatter.

    Since Boost 1.62. 

  21. virtual std::string get_default_stream_description() const;
    Returns a default stream for this logger.

    The returned string describes the stream as if it was passed from the command line "--log_sink" parameter. With that regards, stdout and stderr have special meaning indicating the standard output or error stream respectively.

    Since Boost 1.62. 


PrevUpHomeNext