mirror of
https://github.com/boostorg/test.git
synced 2026-02-22 03:42:07 +00:00
620 lines
17 KiB
Plaintext
620 lines
17 KiB
Plaintext
[#ref_section_runtime_configuration][section Runtime configuration ... or what are the strings I can pull?]
|
|
|
|
|
|
The __UTF__ supports multiple parameters that affect test module execution. To set the parameter's value you can
|
|
either use a runtime configuration subsystem interface from within the test module initialization function or you can
|
|
specify the value at runtime during test module invocation.
|
|
|
|
The __UTF__ provides two ways to set a parameter at runtime: by specifying a command line argument and by setting an
|
|
environment variable. The command line argument always overrides the corresponding environment variable.
|
|
|
|
During test module initialization the __UTF__ parses the command line and excludes all parameters that belong to it and
|
|
their values from the argument list. The rest of command line is forwarded to the test module initialization function
|
|
supplied by you. The command line argument format expected by the __UTF__ is:
|
|
|
|
[pre
|
|
--<command_line_argument_name>=<argument_value>
|
|
]
|
|
|
|
The command line argument name is case sensitive. It is required to match exactly the name in parameter specification.
|
|
There should not be any spaces between '=' and either command line argument name or argument value.
|
|
|
|
|
|
The corresponding environment variable name is also case sensitive and is required to exactly match the name in the
|
|
parameter specification.
|
|
|
|
All information about supported parameters is summarized below in the reference section.
|
|
|
|
[include runtime_configuration.running_specific_test.qbk]
|
|
|
|
|
|
[section Runtime parameters reference]
|
|
Each parameter specification includes:
|
|
|
|
# the full parameter name
|
|
# corresponding environment variable name
|
|
# command line argument name
|
|
# acceptable values and
|
|
# a long description
|
|
|
|
The default value for the parameter is bold in the
|
|
acceptable values list. All values are case sensitive and are required to exactly match the parameter specification.
|
|
|
|
|
|
[table
|
|
[
|
|
[Command]
|
|
[Short description]
|
|
]
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_auto_start_dbg__]
|
|
[Automatically attach debugger in case of system failure.]
|
|
]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_show_progress__]
|
|
[Makes the framework to print progress information. More details [link ref_output_progress here].]
|
|
]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__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]
|
|
]
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_log_level__]
|
|
[Specifies the logging level of the __UTF__]
|
|
]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_run_test__]
|
|
[Specifies which test units to run.]
|
|
]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_output_format__]
|
|
[Specifies the log format and the report format.]
|
|
]
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_report_format__]
|
|
[Specifies the report format.]
|
|
]
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_result_code__]
|
|
[Make the framework return a result code indicating an error in the tests.]
|
|
]
|
|
|
|
[/ ###############################################################################################]
|
|
[
|
|
[__param_report_level__]
|
|
[The level of details carried by the __UTF__ report.]
|
|
]
|
|
|
|
|
|
|
|
]
|
|
[warning There is a link to the Boost.Test debug API, never heard about]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
|
|
[#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]
|
|
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#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]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_log_level][section `log_level`]
|
|
|
|
Allows setting the __UTF__ <link linkid="utf.user-guide.test-output.log">log level</link> in a range from a
|
|
complete log, when all successful tests are confirmed and all test suite messages are included, to an empty
|
|
log when nothing is logged a test output stream.
|
|
|
|
[note Log levels are accumulating, in other words each log level includes also all the information reported by less restrictive ones.]
|
|
|
|
|
|
[h4 Acceptable values]
|
|
|
|
[table Log levels
|
|
[
|
|
[value]
|
|
[feature]
|
|
]
|
|
[
|
|
[all]
|
|
[report all log messages including the passed test notification]
|
|
]
|
|
[
|
|
[success]
|
|
[the same as all]
|
|
]
|
|
[
|
|
[test_suite]
|
|
[Shows test suite messages]
|
|
]
|
|
[
|
|
[message]
|
|
[Shows user messages]
|
|
]
|
|
[
|
|
[warning]
|
|
[Reports warnings issued by user]
|
|
]
|
|
[
|
|
[[*error] (default)]
|
|
[Reports all error conditions]
|
|
]
|
|
[
|
|
[cpp_exception]
|
|
[Reports uncaught C++ exception]
|
|
]
|
|
[
|
|
[system_error]
|
|
[Reports system originated non-fatal errors. For example, timeout or floating point exception.]
|
|
]
|
|
[
|
|
[fatal_error]
|
|
[Reports only user or system originated fatal errors. For example, memory access violation.]
|
|
]
|
|
[
|
|
[nothing]
|
|
[Does not report any information.]
|
|
]
|
|
|
|
]
|
|
|
|
|
|
[h4 Environment variable]
|
|
|
|
BOOST_TEST_LOG_LEVEL
|
|
|
|
[endsect] [/log_level]
|
|
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_run_test][section `run_test`]
|
|
|
|
Specifies the tests to run.
|
|
|
|
|
|
|
|
[h4 Acceptable values]
|
|
|
|
See the related [link ref_runtime_specification_test_to_run documentation] for the format of the acceptable values.
|
|
|
|
[h4 Environment variable]
|
|
|
|
BOOST_TESTS_TO_RUN
|
|
|
|
[endsect] [/run_test]
|
|
|
|
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_output_format][section `output_format`]
|
|
|
|
Combines an effect of __param_report_format__ and __param_log_format__ parameters. Has higher priority than either one of them if specified.
|
|
|
|
|
|
[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_OUTPUT_FORMAT
|
|
|
|
[endsect] [/output_format]
|
|
|
|
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_report_format][section `report_format`]
|
|
|
|
Allows selecting the __UTF__ report format from the list of formats supplied by the framework. To specify a custom report format use unit_test_report API.
|
|
|
|
[warning Provide something concrete to the user]
|
|
|
|
[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_REPORT_FORMAT
|
|
|
|
[endsect] [/report_format]
|
|
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_result_code][section `result_code`]
|
|
|
|
Value "no" enforces the framework to always return zero result code. This could be used for test programs
|
|
executed within GUI. See the [link ref_usage_recommendations usage recommendations] section for more details.
|
|
|
|
[h4 Acceptable values]
|
|
|
|
* [*yes] (default)
|
|
* no
|
|
|
|
|
|
[h4 Environment variable]
|
|
|
|
BOOST_TEST_RESULT_CODE
|
|
|
|
[endsect] [/result_code]
|
|
|
|
|
|
[/ ###############################################################################################]
|
|
[#ref_param_report_level][section `report_level`]
|
|
|
|
Allows setting the level of details carried by the testing results report generated by the framework. Use value
|
|
"no" to eliminate the results report completely. See the
|
|
<xref linkend="utf.user-guide.test-output.results-report"/> for description of different report formats.
|
|
|
|
[h4 Acceptable values]
|
|
|
|
* [*confirm] (default)
|
|
* no
|
|
* short
|
|
* detailed
|
|
|
|
|
|
[h4 Environment variable]
|
|
|
|
BOOST_TEST_REPORT_LEVEL
|
|
|
|
[endsect] [/report_level]
|
|
|
|
|
|
|
|
|
|
<refentry name="detect_fp_exceptions">
|
|
<name>[Do not] trap floating point exceptions</name>
|
|
<env>BOOST_TEST_DETECT_FP_EXCEPTIONS</env>
|
|
<cla>detect_fp_exceptions</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">no</emphasis></member>
|
|
<member>yes</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
enables/disable hardware traps for the floating point exception if they are supported. By default is disabled.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
<refentry name="detect_memory_leaks">
|
|
<name>Detect memory leaks</name>
|
|
<env>BOOST_TEST_DETECT_MEMORY_LEAK</env>
|
|
<cla>detect_memory_leaks</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member>0</member>
|
|
<member><emphasis role="bold">1</emphasis></member>
|
|
<member>integer value > 1</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
Positive value tells the framework to detect the memory leaks (if any). In addition any value greater than 1
|
|
is treated as leak allocation number and setups runtime breakpoint. In other words setting this parameter to
|
|
the positive value N greater than 1 causes the framework to set a breakpoint at Nth memory allocation (don't
|
|
do that from the command line - only when you are under debugger). Note: if your test program produces memory
|
|
leaks notifications, they are combined with allocation number values you could use to set a breakpoint.
|
|
Currently only applies to MS family of compilers in debug builds.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
|
|
|
|
|
|
|
|
<refentry name="log_sink">
|
|
<name>The log sink name</name>
|
|
<env>BOOST_TEST_LOG_SINK</env>
|
|
<cla>log_sink</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">stdout</emphasis></member>
|
|
<member>stderr</member>
|
|
<member>arbitrary file name</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
This parameter allows easily redirect the test log. The parameter value is the string containing either a file
|
|
name, in which case the __UTF__ will redirect log into file with that name, or 'stdout', in which case log is
|
|
redirected into standard output stream, or 'stderr' , in which case log is redirected into standard error stream.
|
|
Default is 'stdout'
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry name="random">
|
|
<name>Random seed for random order of test cases</name>
|
|
<env>BOOST_TEST_RANDOM</env>
|
|
<cla>random</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">0</emphasis></member>
|
|
<member>1</member>
|
|
<member>integer value > 1</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
positive value makes the framework to run the test cases in random order. Also if this value is greater than 1,
|
|
it's used as a random seed. In other case random seed is generated based on current time.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
|
|
|
|
|
|
<refentry name="report_sink">
|
|
<name>The report sink name</name>
|
|
<env>BOOST_TEST_REPORT_SINK</env>
|
|
<cla>report_sink</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">stderr</emphasis></member>
|
|
<member>stdout</member>
|
|
<member>arbitrary file name</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
This parameter allows easily redirect the test results report. The parameter value is the string containing either
|
|
a file name, in which case the __UTF__ will redirect results report into file with that name, or 'stdout', in which case
|
|
report is redirected into standard output stream, or 'stderr', in which case report is redirected into standard error
|
|
stream. Default is 'stderr'.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
|
|
|
|
|
|
|
|
<refentry name="save_patterm">
|
|
<name>Save patterm</name>
|
|
<env>BOOST_TEST_SAVE_PATTERN</env>
|
|
<cla>save_pattern</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">no</emphasis></member>
|
|
<member>yes</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
this parameter serves no particular purpose within the framework itself. It can be used by test modules relying
|
|
on output_test_stream to implement testing logic. output_test_stream has two modes of operation: save the pattern
|
|
file and match against stored pattern. You can use this parameter to switch between these modes, by passing the
|
|
parameter value to the output_test_stream constructor.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
|
|
|
|
<refentry name="use_alt_stack">
|
|
<name>Use alternative stack</name>
|
|
<env>BOOST_TEST_USE_ALT_STACK</env>
|
|
<cla>use_alt_stack</cla>
|
|
<vals>
|
|
<simplelist>
|
|
<member><emphasis role="bold">yes</emphasis></member>
|
|
<member>no</member>
|
|
</simplelist>
|
|
</vals>
|
|
<descr>
|
|
<simpara>
|
|
specifies whether or not the Boost.Test Execution Monitor should employ an alternative stack for signals
|
|
processing on platforms where they are supported.
|
|
</simpara>
|
|
</descr>
|
|
</refentry>
|
|
|
|
</btl-parameter-reference>
|
|
</section>
|
|
</section>
|
|
|
|
[endsect] [/ runtime parameters reference]
|
|
|
|
[endsect] [/ runtime configuration] |