automake-1.16: Command-line arguments for test drivers
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-generated test 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 (⇒Testsuite progress
output).
‘--log-file=PATH.log’
The ‘.log’ file the test driver must create (⇒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 (⇒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 (⇒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 driver is advised, as that
would offer a better consistency and a more pleasant user experience.