the Compartmented Robust Posix C++ Unit Test system

The command line

The command line parameters to a test program is:

<programname> {flags} {names}

{names} is zero or more names of tests or testsuites.

{flags} are zero or more of:


-b / --backtrace-heap

Show the full stack backtrace when heap violations are discovered. This is normally off since it slows down execution considerably for heap intensive tests.

This option is only available if crpcut is compiled with support for backtrace and the program is linked with -lcrpcut instead of -lcrpcut_basic. See Stack backtraces

-C name / --output-charset=name

Define the character set used for non-XML output. The name of the character set must be legal as the tocode parameter to iconv_open()

XML output is always using UTF-8

If no output character set is defined, all textual information is presented raw without conversion.

With a defined output character set, the output is converted from the character set defined for the test program.

The default character set defined for the test program is UTF-8. See crpcut::set_charset()

Characters that cannot be converted from the default character set for the test program, to the output character set, are by default represented by '.' See -I string / --illegal-char=string for changing the representation of characters that cannot be converted.

-c number / --children=number

Set number of parallel test case processes to number. number must be at least 1.

crpcut defaults to one child process

With a multi-core CPU, or with tests that spend a lot of time waiting, using many parallel test case processes can considerably shorten the run time of a test program.

-c / --children cannot be combined with -s / --single-shot
-d dirname / --working-dir=dirname

Set the working directory for crpcut to dirname. dirname may be a relative path. The name dirname must refer to an existing directory that crpcut has write access to. The tests will run in child directories created by crpcut

-I string / --illegal-char=string

Define how to represent output characters that cannot be converted to the output character set.

For XML-output, this defaults to &#xfffd; For text output, this defaults to '.'
-i "a string" / --identity="a string"

The string value given will be the value if the id-tag in the header with XML-output. The command flag has no other purpose.

-l / --list

crpcut::run() prints the names of all tests matching any in {names} (or all tests if {names} is empty) to the output stream and return -1.

-l / --list cannot be combined with any other option.
-L / --list-tags

crpcut::run() prints the names of all tags, defined for the test program, on the output stream and return -1.

-L / --list-tags cannot be combined with any other option.

See WITH_TEST_TAG(tagname) for how to use tags with tests.

-n / --nodeps

Ignore all dependencies and consider all tests available for running.

-n / --nodeps is implied by -s / --single-shot
-o filename / --output=filename

Direct the test report to filename. By default the test report will be in XML format. Combine with -x / --xml to get a human readable report to filename. A report summary will still be printed on stdout unless suppressed with the -q / --quiet.

-o / --output cannot be combined with -s / --single-shot
-p name=value / --param=name=value

Define a named parameter for the tests to use. The syntax is -p name=value or --param=name=value. Several named parameters can be defined with multiple -p / --param options on the command line, each defining a different named parameter.

Tests pick up the values with crpcut::get_parameter().

-q / --quiet

Suppress the printing of a brief report summary, resulting from the -o filename / --output=filename option.

-q / --quiet is implied by -s / --single-shot
-s / --single-shot

Run the one test that matches {names}, without spawning a separate test process. Only one single test can be selected. This is useful for running a test in a debugger.

This is a markedly different environment where many of the crpcut features are unavailable. stdout and stderr have their normal functions, instead of being processed by crpcut. INFO is sent to stdout. It is not possible for crpcut to monitor time consumed by the test case, and neither is it possible to monitor abnormal exits. Any failed assertion results in a call to abort().

Extend all timeouts by multiplying the timeout times, including the defaulted timeouts, with factor. The factor must be a positive integer.

--timeout-multiplier=factor cannot be combined with -s / --single-shot or -t / --disable-timeouts.
-t / --disable-timeouts

Never fail a test due to its time consumption. This can be useful when running tests under time consuming tools like valgrind

This turns off the safe guard of crpcut that kills tests that have no progress (infinite loops, sleeps, etc.) If you run tests under slow tools like valgrind, use --timeout-multiplier=factor instead.
-t / --disable-timeouts cannot be combined with -s / --single-shot or --timeout-multiplier.
-T {select}{/non-critical} / --tags={select}{/non-critical}

Select tests to run based on their tag, and which tags represent non-critical tests.

select and non-critical are comma separated lists of tags. If a list begins with - the list is subtractive from the full set of tags in the test program.

If {select} is omitted, all tags are included. If {/non-critical} is omitted, all tests are critical. Untagged tests are always critical.


    ./testprog --tags=-known_bugs,very_slow/in_development

runs all tests except those tagged with known_bugs or very_slow. Tests tagged in_development are non-critical.

See -L / --list-tags for listing all available tags, and WITH_TEST_TAG(tagname) for how to tag a test.

-v / --verbose

Include the output from passed tests in the report.

-v / --verbose is implied by -s / --single-shot
-x / --xml

Switch between XML and human readable test report format. A test report to stdout defaults to human readable, but is changed to XML using -x / --xml. A test report to a named file, using -o filename / --output=filename, defaults to XML but is changed to human readable using -x / --xml.

-x / --xml cannot be combined with -s / --single-shot


    testprog --nodeps --parameter=pwd=`pwd` suite_1

Will run all tests in the testsuite suite_1 regardless of dependencies, and will provide the named parameter pwd the name of the current working directory.