Currently, the TAP driver that comes with Automake requires some by-hand
steps on the developer’s part (this situation should hopefully be improved
in future Automake versions). You’ll have to grab the tap-driver.sh
script from the Automake distribution by hand, copy it in your source tree,
and use the Automake support for third-party test drivers to instruct the
harness to use the tap-driver.sh script and the awk program found
by AM_INIT_AUTOMAKE to run your TAP-producing tests. See the example
below for clarification.
Apart from the options common to all the Automake test drivers
(see Command-line arguments for test drivers), tap-driver.sh
supports the following options, whose names are chosen for enhanced
compatibility with the prove utility.
Causes the test driver to ignore the exit status of the test scripts; by default, the driver will report an error if the script exits with a non-zero status. This option has effect also on non-zero exit statuses due to termination by a signal.
Instruct the test driver to display TAP diagnostics (i.e., lines beginning with the ‘#’ character) in the testsuite progress output too; by default, TAP diagnostics are only copied to the .log file.
Revert the effects of --comments.
Instruct the test driver to merge the test scripts’ standard error into their standard output. This is necessary if you want to ensure that diagnostics from the test scripts are displayed in the correct order relative to test results; this can be of great help in debugging (especially if your test scripts are shell scripts run with shell tracing active). As a downside, this option might cause the test harness to get confused if anything that appears on standard error looks like a test result. Use --stderr-prefix to prefix each line of standard error to avoid this problem.
Revert the effects of --merge.
Prefix each line of the test script’s standard error with
STRING. Defaults to the empty string. This option makes
it possible to avoid parsing ambiguity when --merge is in use,
but it can also be used without --merge to make it easier to
read test log files. When used with --merge, users will
typically want to start STRING with ‘#’, which starts
a TAP comment. The ‘#’ character is difficult to portably include
in a make variable, so the following quadrigraph
substitutions, copied from Autoconf (see Quadrigraphs in The Autoconf Manual), are performed on STRING:
Replaced with ‘#’.
Replaced with the empty string. This makes it possible to include the literal characters ‘@%:@’ in the prefix (‘@%@&t@:@’, for example).
For example, the option ‘--stderr-prefix "@%:@[stderr] "’ passed on the command line will prefix each line of the test script’s standard error with ‘#[stderr] ’.
For more details on --stderr-prefix processing, especially the occasional output reordering due to a race condition, see TAP prefixing stderr.
Change the string that introduces TAP diagnostics from the default value
of “#” to STRING. This can be useful if your
TAP-based test scripts produce verbose output on which they have limited
control (because, say, the output comes from other tools invoked in the
scripts), and it might contain text that gets spuriously interpreted as
TAP diagnostics: such an issue can be solved by redefining the string that
activates TAP diagnostics to a value you know won’t appear by chance in
the tests’ output. Note however that this feature is non-standard, as
the “official” TAP protocol does not allow for such a customization; so
don’t use it if you can avoid it.