diff --git a/doc/v2/runtime_configuration.qbk b/doc/v2/runtime_configuration.qbk index 60277bb7..febd0bc7 100644 --- a/doc/v2/runtime_configuration.qbk +++ b/doc/v2/runtime_configuration.qbk @@ -44,124 +44,201 @@ acceptable values list. All values are case sensitive and are required to exactl [table [ [Command] - [Environment variable] - [Acceptable values] - [Description] + [Short description] ] - - [/ ###############################################################################################] [ - [`auto_start_dbg`] - [`BOOST_TEST_AUTO_START_DBG`] - [ - -* [*`no`] -* `yes` -* `debugger identifier` - - ] - [ -Specifies whether Boost.Test should try to attach a debugger in case if fatal system error occurs. If value is `yes` -the default debugger configured for the platform is going to be attempted. Alternatively the debugger identified -by the argument value of the parameter is used. For more details on advanced debugger support in Boost.Test check - section dedicated to Boost.Test debug API. - ] + [__param_auto_start_dbg__] + [Automatically attach debugger in case of system failure.] ] [/ ###############################################################################################] [ - [[#ref_param_show_progress]`show_progress`] - [`BOOST_TEST_SHOW_PROGRESS`] - [ - -* [*`no`] -* `yes` - - ] + [__param_show_progress__] [Makes the framework to print progress information. More details [link ref_output_progress here].] ] [/ ###############################################################################################] [ - [`build_info`] - [`BOOST_TEST_BUILD_INFO`] - [ - -* [*`no`] -* `yes` - - ] - [Print build information that include: platform, compiler, STL implementation in use and boost version.] + [__param_build_info__] + [Print build information.] ] + [/ ###############################################################################################] + [ + [__param_catch_system__] + [Catch system errors.] + ] - -] + [/ ###############################################################################################] + [ + [__param_break_exec_path__] + [Break execution path] + ] + + [/ ###############################################################################################] + [ + [__param_param_color_output__] + [Produce colour output] + ] + + [ + [__param_log_format__] + [Specifies the log format] + ] +] [warning There is a link to the Boost.Test debug API, never heard about] +[/ ###############################################################################################] - - Break execution path - BOOST_TEST_BREAK_EXEC_PATH - break_exec_path" - - - string consisting of space separate test_name:execution_path_number pairs - - - - - this runtime parameter is used by exception safety tester. By default exception safety tester only reports index of - execution path and test case name where failure occurred. Using this parameter you can make the tester to break the - execution right before entering this path. - - - +[#ref_param_show_progress][section `show_progress`] + +Makes the framework to print progress information. More details [link ref_output_progress here]. + +[h4 Acceptable values] + +* [*no] (default) +* yes + +[h4 Environment variable] + + BOOST_TEST_SHOW_PROGRESS + +[endsect] + +[/ ###############################################################################################] + +[#ref_param_build_info][section `build_info`] + +Print build information that include: + +* platform +* compiler +* STL implementation in use and +* boost version + +[h4 Acceptable values] + +* [*no] (default) +* yes + +[h4 Environment variable] + + BOOST_TEST_BUILD_INFO + +[endsect] [/ build_info] + +[/ ###############################################################################################] + +[#ref_param_auto_dbg][section `auto_start_dbg`] + +Automatically attach debugger in case of system failure. + +Specifies whether Boost.Test should try to attach a debugger in case if fatal system error occurs. If value is ['yes] +the default debugger configured for the platform is going to be attempted. Alternatively the debugger identified +by the argument value of the parameter is used. For more details on advanced debugger support in Boost.Test check + section dedicated to Boost.Test debug API. + +[h4 Acceptable values] + +* [*no] +* yes +* ['debugger identifier] + +[h4 Environment variable] + + BOOST_TEST_AUTO_START_DBG + + +[warning There is a link to the Boost.Test debug API, never heard about] +[endsect] [/auto_start_dbg] - - Catch system errors - BOOST_TEST_CATCH_SYSTEM_ERRORS - catch_system_errors - - - yes - no - - - - - value "no" prohibits the framework from catching asynchronous system events. This could be used for test programs - executed within GUI or to get a coredump for stack analysis. See usage recommendations page for more details. - - - +[/ ###############################################################################################] +[#ref_param_catch_system][section `catch_system_errors`] + +Value "no" prohibits the framework from catching asynchronous system events. This could be used for test programs +executed within GUI or to get a coredump for stack analysis. See [link ref_usage_recommendations usage recommendations] pages for more details. + +[h4 Acceptable values] + +* [*yes] (default) +* no + +[h4 Environment variable] + + BOOST_TEST_CATCH_SYSTEM_ERRORS + +[endsect] [/catch_system_errors] + +[/ ###############################################################################################] +[#ref_param_break_exe_path][section `break_exec_path`] + +this runtime parameter is used by exception safety tester. By default exception safety tester only reports index of +execution path and test case name where failure occurred. Using this parameter you can make the tester to break the +execution right before entering this path. + +[h4 Acceptable values] + +* string consisting of space separate test_name:execution_path_number pairs + + +[h4 Environment variable] + + BOOST_TEST_BREAK_EXEC_PATH + +[endsect] [/break_exec_path] + + + +[/ ###############################################################################################] +[#ref_param_color_output][section `color_output`] + +The __UTF__ is able to produce colour output on systems which supports it. To enable this behaviour set the parameter to +`yes`. By default the output produces in not coloured. + + +[h4 Acceptable values] + +* [*no] (default) +* yes + + +[h4 Environment variable] + + BOOST_TEST_COLOR_OUTPUT + +[endsect] [/color_output] + +[/ ###############################################################################################] +[#ref_param_log_format][section `log_format`] + +Allows selecting the __UTF__ log format from the list of formats supplied by the framework. To specify custom log +format use the [link ref_log_formatter_api custom log formatting API]. + + + +[h4 Acceptable values] + +* [*HRF] (default) +* XML + +HRF stands for human readable format, while XML is dedicated to automated output processing + +[h4 Environment variable] + + BOOST_TEST_LOG_FORMAT + +[endsect] [/log_format] + - - Produce color output - BOOST_TEST_COLOR_OUTPUT - color_output - - - no - yes - - - - - The __UTF__ is able to produce color output on systems which supports it. To enable this behavior set the parameter to - 'yes'. By default the output produces in not colored. - - - [Do not] trap floating point exceptions @@ -203,23 +280,7 @@ by the argument value of the parameter is used. For more details on advanced deb - - The log format - BOOST_TEST_LOG_FORMAT - log_format - - - HRF - human readable format - XML - XML format for automated output processing - - - - - allows selecting the __UTF__ log format from the list of formats supplied by the framework. To specify custom log - format use the unit_test_log API. - - - + The __UTF__ log level diff --git a/doc/v2/test.qbk b/doc/v2/test.qbk index 532d733b..378615b8 100644 --- a/doc/v2/test.qbk +++ b/doc/v2/test.qbk @@ -120,11 +120,16 @@ [def __param_show_progress__ [link ref_param_show_progress `show_progress`]] [def __param_log_level__ [*log_level]] [def __param_output_format__ [*output_format]] -[def __param_log_format__ [*log_format]] +[def __param_log_format__ [link ref_param_log_format `log_format`]] [def __param_run_test__ [*run_test]] [def __param_report_level__ [*report_level]] -[def __param_catch_system__ [*catch_system_error]] +[def __param_catch_system__ [link ref_param_catch_system `catch_system_error`]] [def __param_result_code__ [*result_code]] +[def __param_build_info__ [link ref_param_build_info `build_info`]] +[def __param_auto_start_dbg__ [link ref_param_auto_dbg `auto_start_dbg`]] +[def __param_break_exec_path__ [link ref_param_break_exe_path `break_exec_path`]] +[def __param_param_color_output__ [link ref_param_color_output `color_output`]] + [/=============================================================================] diff --git a/doc/v2/usage_recommandations.qbk b/doc/v2/usage_recommandations.qbk index 589e529e..5238fc6d 100644 --- a/doc/v2/usage_recommandations.qbk +++ b/doc/v2/usage_recommandations.qbk @@ -1,4 +1,4 @@ -[section The unit test framework usage recommendations] +[#ref_usage_recommendations][section The unit test framework usage recommendations] On following pages collected tips and recommendations on how to use and apply the &utf; in your real life practice. @@ -90,8 +90,12 @@ Now run the test again under debugger and it will break at the point of failure. [h4 If you got fatal exception somewhere within test case, make program generate coredump by adding extra command line argument] If you got "memory access violation" message (or any other message indication fatal or system error) when you -run you test, to get more information about the error location add --catch_system_errors=no to the test run -command line. Now run the test again and it will create a coredump you could analyze using you preferable +run you test, to get more information about the error location add +`` +--__param_catch_system__=no +`` + +to the test run command line. Now run the test again and it will create a coredump you could analyse using you preferable debugger. Or run it under debugger in a first place and it will break at the point of failure. [h4 How to use test module build with Boost.Test framework under management of automated regression test facilities?] @@ -102,8 +106,7 @@ My first recommendation is to make sure that the test framework catches all fata `` to all test modules invocations. Otherwise test program may produce unwanted dialogs (depends on compiler and OS) that will halt you -regression tests run. The second recommendation is to -suppress result report output by adding +regression tests run. The second recommendation is to suppress result report output by adding `` --__param_report_level__=no diff --git a/doc/v2/utf.user-guide.test-output.qbk b/doc/v2/utf.user-guide.test-output.qbk index 1199b834..15903d2f 100644 --- a/doc/v2/utf.user-guide.test-output.qbk +++ b/doc/v2/utf.user-guide.test-output.qbk @@ -399,8 +399,10 @@ active log level threshold. While many test log configuration tasks can be performed at runtime using predefined framework parameters, the __UTF__ provides a compile time interface as well. The interface gives you full power over what, where and how to -log. The interface is provided by singleton class boost::unit_test::unit_test_log_t and is -accessible through local file scope reference to single instance of this class: boost::unit_test::unit_test_log. +log. The interface is provided by singleton class ``boost::unit_test::unit_test_log_t`` and is +accessible through local file scope reference to single instance of this class + +``boost::unit_test::unit_test_log`` [section:log_ct_output_stream_redirection Log output stream redirection] @@ -434,6 +436,8 @@ cases. There are no limitations on number of output stream resets either. [endsect] [/section:log_ct_output_stream_redirection] + + [section:log_ct_log_level Log level configuration] If you need to enforce specific log level from within your test module use the following interface: @@ -483,8 +487,7 @@ format selection. [endsect] [/section:log_ct_log_format] - -[section:custom_log_formatter Custom log format support] +[#ref_log_formatter_api][section:custom_log_formatter Custom log format support] [warning Check what to do on this one]