libs/test/doc/test_output/test_tools_support.qbk

[/
 / Copyright (c) 2015 Boost.Test contributors
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:test_tools_support_for_logging Tools supports for logging]


[/ -------------------------------------------------------------------------------------------------- ]
[section:testing_tool_output_disable Logging user defined types]

Most of the [link boost_test.testing_tools testing tools] print values of their
arguments to the output stream in some form of log statement. If arguments type does not support
``
  operator<<(std::ostream&, ArgumentType const&);
``
interface, you will get a compilation error.

The __UTF__ supports three different methods for logging user defined types:

# through the `operator<<` for that specific type: any type that implements the above interface has direct support for
  logging,
# through a customization point responsible for logging a specific type, which is less intrusive than the implementation
  of `operator<<`. This is explained in more details in [link ref_log_output_custom_customization_point this section],
# by prohibiting the [link boost_test.testing_tools testing tools] from logging argument values for
  specified type through __BOOST_TEST_DONT_PRINT_LOG_VALUE__.
  This is explained in more details in [link ref_log_output_custom_avoid_printing this section].

[#ref_log_output_custom_customization_point]
[h4 User type customization point for logging]
It is possible to indicate a function, `boost_test_print_type`, to __UTF__ that is responsible for the printing of a user defined type, without
the need to override the `operator<<` for that specific type. This is convenient for instance when
the `operator<<` has already been defined for other needs.

The syntax follows the `operator<<`, and this function should be in the same namespace as the type:

```
std::ostream& boost_test_print_type(std::ostream& ostr, ArgumentType const& right);
```

[bt_example logger-customization-point..Logging customization point usage..run-fail]

[#ref_log_output_custom_avoid_printing]
[h4 Prohibiting the printing of a specific type]
To prohibit the printing of a specific type, use the following statement on file level before first
test case that includes statement failing to compile:

``
  BOOST_TEST_DONT_PRINT_LOG_VALUE(ArgumentType)
``

[bt_example example32..BOOST_TEST_DONT_PRINT_LOG_VALUE usage..run-fail]

[endsect] [/section:testing_tool_output_disable]

[/ -------------------------------------------------------------------------------------------------- ]
[section:test_output_macro_message Custom messages]
The macro __BOOST_TEST_MESSAGE__ is intended to be used for the purpose of injecting an additional message into the
__UTF__ test log. These messages are not intended to indicate any error or warning conditions, but rather as
information/status notifications. The macro signature is as follows:

  __BOOST_TEST_MESSAGE__(test_message);

The test_message argument can be as simple as C string literal or any custom expression that you can produce with in a
manner similar to standard `std::iostream` operation.

[important Messages generated by this tool do not appear in test log output with default value of the active log level
   threshold. For these messages to appear the active log level threshold has to be set to a value below or equal
   to "message".
]

[bt_example example21..__BOOST_TEST_MESSAGE__ usage..run]

[endsect] [/section:test_output_macro_message]

[/ -------------------------------------------------------------------------------------------------- ]

[include checkpoints.qbk]
[include contexts.qbk]
[include logging_floating_point.qbk]

[endsect] [/ Tools supports for logging]
Boost C++ Libraries

libs/test/doc/test_output/test_tools_support.qbk
