mirror of
https://github.com/boostorg/test.git
synced 2026-01-30 08:22:12 +00:00
Continuing the reference parameters section
changes the format: a summary table and separate sections for each elements fixed/improved some links
This commit is contained in:
Raffi Enficiaud
@@ -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
|
||||
<!-- TO FIX: add link --> 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]
|
||||
|
||||
|
||||
[/ ###############################################################################################]
|
||||
|
||||
<refentry name="break_exec_path">
|
||||
<name>Break execution path</name>
|
||||
<env>BOOST_TEST_BREAK_EXEC_PATH</env>
|
||||
<cla>break_exec_path"</cla>
|
||||
<vals>
|
||||
<simplelist>
|
||||
<member>string consisting of space separate test_name:execution_path_number pairs</member>
|
||||
</simplelist>
|
||||
</vals>
|
||||
<descr>
|
||||
<simpara>
|
||||
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.
|
||||
</simpara>
|
||||
</descr>
|
||||
</refentry>
|
||||
[#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
|
||||
<!-- TO FIX: add link --> 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]
|
||||
|
||||
|
||||
|
||||
<refentry name="catch_system_errors">
|
||||
<name>Catch system errors</name>
|
||||
<env>BOOST_TEST_CATCH_SYSTEM_ERRORS</env>
|
||||
<cla>catch_system_errors</cla>
|
||||
<vals>
|
||||
<simplelist>
|
||||
<member><emphasis role="bold">yes</emphasis></member>
|
||||
<member>no</member>
|
||||
</simplelist>
|
||||
</vals>
|
||||
<descr>
|
||||
<simpara>
|
||||
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.
|
||||
</simpara>
|
||||
</descr>
|
||||
</refentry>
|
||||
[/ ###############################################################################################]
|
||||
[#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]
|
||||
|
||||
|
||||
<refentry name="color_output">
|
||||
<name>Produce color output</name>
|
||||
<env>BOOST_TEST_COLOR_OUTPUT</env>
|
||||
<cla>color_output</cla>
|
||||
<vals>
|
||||
<simplelist>
|
||||
<member><emphasis role="bold">no</emphasis></member>
|
||||
<member>yes</member>
|
||||
</simplelist>
|
||||
</vals>
|
||||
<descr>
|
||||
<simpara>
|
||||
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.
|
||||
</simpara>
|
||||
</descr>
|
||||
</refentry>
|
||||
|
||||
<refentry name="detect_fp_exceptions">
|
||||
<name>[Do not] trap floating point exceptions</name>
|
||||
@@ -203,23 +280,7 @@ by the argument value of the parameter is used. For more details on advanced deb
|
||||
</descr>
|
||||
</refentry>
|
||||
|
||||
<refentry name="log_format">
|
||||
<name>The log format</name>
|
||||
<env>BOOST_TEST_LOG_FORMAT</env>
|
||||
<cla>log_format</cla>
|
||||
<vals>
|
||||
<simplelist>
|
||||
<member><emphasis role="bold">HRF</emphasis> - human readable format</member>
|
||||
<member>XML - XML format for automated output processing</member>
|
||||
</simplelist>
|
||||
</vals>
|
||||
<descr>
|
||||
<simpara>
|
||||
allows selecting the __UTF__ log format from the list of formats supplied by the framework. To specify custom log
|
||||
format use the <link linkend="utf.user-guide.test-output.log.ct-config.log-formatter">unit_test_log API</link>.
|
||||
</simpara>
|
||||
</descr>
|
||||
</refentry>
|
||||
|
||||
|
||||
<refentry name="log_level">
|
||||
<name>The __UTF__ log level</name>
|
||||
|
||||
@@ -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`]]
|
||||
|
||||
|
||||
[/=============================================================================]
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 <classname>boost::unit_test::unit_test_log_t</classname> 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]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user