Runtime parameters reference

| > The Unit Test Framework > User's guide > Runtime configuration > Parameters reference |

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

- auto_start_dbg
- build_info
- catch_system_errors
- detect_memory_leak
- detect_fp_exceptions
- log_format
- log_level
- output_format
- random
- report_format
- report_level
- result_code
- run_test
- show_progress
- use_alt_stack

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 | : | 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 | : | Detect memory leaks
Environment variable name | : | `BOOST_TEST_DETECT_MEMORY_LEAK`
Command line argument name | : | `build_info`

Acceptable Values

:

0
1
integer value > 1

Description | : | positive value tells the framework to detect the memory leaks (if any). Any value greater then 1 in addition is treated as leak allocation number and setup 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 produce 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.

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 | : | 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 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`

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_LOG_FORMAT`
Command line argument name | : | `log_format`

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 | : | [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 | : | 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.