Home > The Unit Test Framework > User's guide > Runtime configuration > Parameters reference
PrevNext
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.

Parameter Name : Automatically attach debugger in case of system failure
Environment variable name : BOOST_TEST_AUTO_START_DBG
Command line argument name : auto_start_dbg
Acceptable Values :
no
yes
debugger identifier
Description :

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.


Parameter Name : Break execution path
Environment variable name : BOOST_TEST_BREAK_EXEC_PATH
Command line argument name : break_exec_path"
Acceptable Values :
string consisting of space separate test_name:execution_path_number pairs
Description :

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.


Parameter Name : Print build info
Environment variable name : BOOST_TEST_BUILD_INFO
Command line argument name : build_info
Acceptable Values :
no
yes
Description :

makes the framework to print build information that include: platform, compiler, STL implementation in use and boost version.


Parameter Name : Catch system errors
Environment variable name : BOOST_TEST_CATCH_SYSTEM_ERRORS
Command line argument name : catch_system_errors
Acceptable Values :
yes
no
Description :

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.


Parameter Name : Produce color output
Environment variable name : BOOST_TEST_COLOR_OUTPUT
Command line argument name : color_output
Acceptable Values :
no
yes
Description :

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.


Parameter Name : [Do not] trap floating point exceptions
Environment variable name : BOOST_TEST_DETECT_FP_EXCEPTIONS
Command line argument name : detect_fp_exceptions
Acceptable Values :
no
yes
Description :

enables/disable hardware traps for the floating point exception if they are supported. By default is disabled.


Parameter Name : Detect memory leaks
Environment variable name : BOOST_TEST_DETECT_MEMORY_LEAK
Command line argument name : detect_memory_leaks
Acceptable Values :
0
1
integer value > 1
Description :

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.


Parameter Name : The log format
Environment variable name : BOOST_TEST_LOG_FORMAT
Command line argument name : log_format
Acceptable Values :
HRF - human readable format
XML - XML format for automated output processing
Description :

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.


Parameter Name : The UTF log level
Environment variable name : BOOST_TEST_LOG_LEVEL
Command line argument name : log_level
Acceptable Values :

all -

report all log messages including the passed test notification

success -

the same as all

test_suite -

show test suite messages

message -

show user messages

warning -

report warnings issued by user

error -

report all error conditions

cpp_exception -

report uncaught c++ exception

system_error -

report system originated non-fatal errors (for example, timeout or floating point exception)

fatal_error -

report only user or system originated fatal errors (for example, memory access violation)

nothing -

do not report any information
Description :

allows setting the UTF log level 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 that log levels are accumulating, in other words each log level includes also all the information reported by less restrictive ones.


Parameter Name : The log sink name
Environment variable name : BOOST_TEST_LOG_SINK
Command line argument name : log_sink
Acceptable Values :
stdout
stderr
arbitrary file name
Description :

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'


Parameter Name : The output format
Environment variable name : BOOST_TEST_OUTPUT_FORMAT
Command line argument name : output_format
Acceptable Values :
HRF - human readable format
XML - XML format for automated output processing
Description :

combines an effect of report_format and log_format parameters. Has higher priority than either one of them if specified.


Parameter Name : Random seed for random order of test cases
Environment variable name : BOOST_TEST_RANDOM
Command line argument name : random
Acceptable Values :
0
1
integer value > 1
Description :

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.


Parameter Name : The report format
Environment variable name : BOOST_TEST_REPORT_FORMAT
Command line argument name : report_format
Acceptable Values :
HRF - human readable format
XML - XML format for automated output processing
Description :

allows selecting the UTF report format from the list of formats supplied by the framework. To specify custom report format use unit_test_report API.


Parameter Name : The results report level
Environment variable name : BOOST_TEST_REPORT_LEVEL
Command line argument name : report_level
Acceptable Values :
no
confirm
short
detailed
Description :

allows setting the level of detailization for the testing results report generated by the framework. Use value "no" to eliminate the results report completely. See the the section called “Test report output” for description of different report formats.


Parameter Name : The report sink name
Environment variable name : BOOST_TEST_REPORT_SINK
Command line argument name : report_sink
Acceptable Values :
stderr
stdout
arbitrary file name
Description :

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'.


Parameter Name : [Do not] return result code
Environment variable name : BOOST_TEST_RESULT_CODE
Command line argument name : result_code
Acceptable Values :
yes
no
Description :

value "no" enforces the framework to always return zero result code. This could be used for test programs executed within GUI. See usage recommendations section for more details.


Parameter Name : Test units to run
Environment variable name : BOOST_TESTS_TO_RUN
Command line argument name : run_test
Acceptable Values :
specification of test units to run
Description :

specifies which test units to run.


Parameter Name : Save patterm
Environment variable name : BOOST_TEST_SAVE_PATTERN
Command line argument name : save_pattern
Acceptable Values :
no
yes
Description :

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.


Parameter Name : Show progress
Environment variable name : BOOST_TEST_SHOW_PROGRESS
Command line argument name : show_progress
Acceptable Values :
no
yes
Description :

makes the framework to print progress information.

Parameter Name : Use alternative stack
Environment variable name : BOOST_TEST_USE_ALT_STACK
Command line argument name : use_alt_stack
Acceptable Values :
yes
no
Description :

specifies whether or not the Boost.Test Execution Monitor should employ an alternative stack for signals processing on platforms where they are supported.


Copyright © 2001-2012 Gennadiy Rozental
PrevUpHomeNext