15.3.3.1 Command-line arguments for test drivers

A custom driver can rely on various command-line options and arguments being passed to it automatically by the Automake's parallel-tests harness. It is mandatory that it understands all of them (even if the exact interpretation of the associated semantics can legitimately change between a test driver and another, and even be a no-op in some drivers).

Here is the list of options:

--test-name=NAME

The name of the test, with VPATH prefix (if any) removed. This can have a suffix and a directory component (as in e.g., sub/foo.test), and is mostly meant to be used in console reports about testsuite advancements and results (see Testsuite progress output).

--log-file=PATH.log

The .log file the test driver must create (see Basics of test metadata). If it has a directory component (as in e.g., sub/foo.log), the test harness will ensure that such directory exists before the test driver is called.

--trs-file=PATH.trs

The .trs file the test driver must create (see Basics of test metadata). If it has a directory component (as in e.g., sub/foo.trs), the test harness will ensure that such directory exists before the test driver is called.

--color-tests={yes|no}

Whether the console output should be colorized or not (see Simple tests and color-tests, to learn when this option gets activated and when it doesn't).

--expect-failure={yes|no}

Whether the tested program is expected to fail.

--enable-hard-errors={yes|no}

Whether “hard errors” in the tested program should be treated differently from normal failures or not (the default should be yes). The exact meaning of “hard error” is highly dependent from the test protocols or conventions in use.

--

Explicitly terminate the list of options.

The first non-option argument passed to the test driver is the program to be run, and all the following ones are command-line options and arguments for this program.

Note that the exact semantics attached to the --color-tests, --expect-failure and --enable-hard-errors options are left up to the individual test drivers. Still, having a behaviour compatible or at least similar to that provided by the default parallel-tests driver is advised, as that would offer a better consistency and a more pleasant user experience.