15.2.1.1 Testsuite Environment Overrides

The AM_TESTS_ENVIRONMENT and TESTS_ENVIRONMENT variables can be used to run initialization code and set environment variables for the test scripts. The former variable is developer-reserved, and can be defined in the Makefile.am, while the latter is reserved for the user, which can employ it to extend or override the settings in the former; for this to work portably, however, the contents of a non-empty AM_TESTS_ENVIRONMENT must be terminated by a semicolon.

The AM_TESTS_FD_REDIRECT variable can be used to define file descriptor redirections for the test scripts. One might think that AM_TESTS_ENVIRONMENT could be used for this purpose, but experience has shown that doing so portably is practically impossible. The main hurdle is constituted by Korn shells, which usually set the close-on-exec flag on file descriptors opened with the exec builtin, thus rendering an idiom like AM_TESTS_ENVIRONMENT = exec 9>&2; ineffectual. This issue also affects some Bourne shells, such as the HP-UX’s /bin/sh.

AM_TESTS_ENVIRONMENT = \
## Some environment initializations are kept in a separate shell
## file 'tests-env.sh', which can make it easier to also run tests
## from the command line.
  . $(srcdir)/tests-env.sh; \
## On Solaris, prefer more POSIX-compliant versions of the standard
## tools by default.
  if test -d /usr/xpg4/bin; then \
    PATH=/usr/xpg4/bin:$$PATH; export PATH; \
  fi;

## With this, the test scripts will be able to print diagnostic
## messages to the original standard error stream, even if the test
## driver redirects the stderr of the test scripts to a log file
## before executing them.
AM_TESTS_FD_REDIRECT = 9>&2

As another example, a notice that a test is starting can be emitted using AM_TESTS_ENVIRONMENT (for package maintainers) or TESTS_ENVIRONMENT by users:

make -j12 ... TESTS_ENVIRONMENT='echo RUNNING: "$$f";' check

The shell variable $f contains the test name. (Although technically this is not guaranteed, in practice it is extremely unlikely to ever change.) This can be helpful to see when trying to debug test failures.

Notwithstanding these benefits, AM_TESTS_ENVIRONMENT is, for historical and implementation reasons, not supported by the serial harness (see Older (and discouraged) Serial Test Harness).