tests/README

   1                             The Automake test suite
   2
   3
   4 User interface
   5 ==============
   6
   7
   8 Running all tests
   9 -----------------
  10
  11   make check
  12
  13   You can use `-jN' for faster completion (it even helps on a
  14   uniprocessor system, due to unavoidable sleep delays, as
  15   noted below).
  16
  17
  18 Interpretation
  19 --------------
  20
  21   Successes:
  22     PASS  - success
  23     XFAIL - expected failure
  24
  25   Failures:
  26     FAIL  - failure
  27     XPASS - unexpected success
  28
  29   Other:
  30     SKIP  - skipped tests (third party tools not available)
  31
  32
  33 Getting details from failures
  34 -----------------------------
  35
  36   Each test is a shell script, and by default is run by /bin/sh.
  37   In a non-VPATH build you can run them directly, they will be verbose.
  38   By default, verbose output of a test foo.test is retained in the log
  39   file foo.log.  A summary log is created in the file test-suite.log.
  40
  41   You can limit the set of files using the TESTS variable, and enable
  42   detailed test output at the end of the test run with the VERBOSE
  43   variable:
  44
  45     env VERBOSE=x TESTS='first.test second.test ...' make -e check
  46
  47
  48 Supported shells
  49 ----------------
  50
  51   The test scripts are written with portability in mind, so that they
  52   should run with any decent Bourne-compatible shell.
  53
  54   However, some care must be used with Zsh, since, when not directly
  55   starting in Bourne-compatibility mode, it has some incompatibilities
  56   in the handling of `$0' which conflict with our usage, and which have
  57   no easy workaround.  Thus, if you want to run a test script, say
  58   foo.test, with Zsh, you *can't* simply do `zsh foo.test', but you
  59   *must* resort to:
  60     zsh -o no_function_argzero foo.test
  61
  62   Note that this problem does not occur if zsh is executed through a
  63   symlink with a basename of `sh', since in that case it starts
  64   in Bourne compatibility mode.  So you should be perfectly safe when
  65   /bin/sh is zsh.
  66
  67
  68 Reporting failures
  69 ------------------
  70
  71   Send verbose output, i.e., the contents of test-suite.log, of failing
  72   tests to <bug-automake@gnu.org>, along with the usual version numbers
  73   (which Automake, which Autoconf, which operating system, which make
  74   version, which shell, etc.)
  75
  76
  77
  78 Writing test cases
  79 ==================
  80
  81
  82 Do
  83 --
  84
  85   If you plan to fix a bug, write the test case first.  This way you'll
  86   make sure the test catches the bug, and that it succeeds once you have
  87   fixed the bug.
  88
  89   Add a copyright/license paragraph.
  90
  91   Explain what the test does.
  92
  93   Cite the PR number (if any), and the original reporter (if any), so
  94   we can find or ask for information if needed.
  95
  96   If a test checks examples or idioms given in the documentation, make
  97   sure the documentation reference them appropriately in comments, as in:
  98     @c Keep in sync with autodist-config-headers.test.
  99     @example
 100     ...
 101     @end example
 102
 103   Use `required=...' for required tools.  Do not explicitly require
 104   tools which can be taken for granted because they're listed in the
 105   GNU Coding Standards (for example, `gzip').
 106
 107   Include ./defs in every test script (see existing tests for examples
 108   of how to do this).
 109
 110   Use the `skip_' function to skip tests, with a meaningful message if
 111   possible.  Where convenient, use the `warn_' function to print generic
 112   warnings, the `fail_' function for test failures, and the `fatal_'
 113   function for hard errors.  In case a hard error is due to a failed
 114   set-up of a test scenario, you can use the `framework_fail_' function
 115   instead.
 116
 117   For tests that use the `parallel-tests' Automake option, set the shell
 118   variable `parallel_tests' to "yes" before including ./defs.  Also,
 119   do not use for them a name that ends in `-p.test', since that would
 120   risk to clash with automatically-generated tests.  For tests that are
 121   *not* meant to work with the `parallel-tests' Automake option (these
 122   should be very very few), set the shell variable `parallel_tests' to
 123   "no" before including ./defs.
 124
 125   ./defs sets a skeleton configure.in.  If possible, append to this
 126   file.  In some cases you'll have to overwrite it, but this should
 127   be the exception.  Note that configure.in registers Makefile.in
 128   but do not output anything by default.  If you need ./configure
 129   to create Makefile, append AC_OUTPUT to configure.in.
 130
 131   Use `set -e' to catch failures you might not have thought of.
 132
 133   End the test script with a `:' or `Exit 0'.  Otherwise, when somebody
 134   changes the test by adding a failing command after the last command,
 135   the test will spuriously fail because $? is nonzero at the end.
 136   Note that this is relevant also for tests using `set -e', if they
 137   contain commands like "grep ... Makefile.in && Exit 1" (and there
 138   are indeed a lot of such tests).
 139
 140   Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
 141   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
 142   commands.
 143
 144   Use $sleep when you have to make sure that some file is newer
 145   than another.
 146
 147   Use `cat' or `grep' to display (part of) files that may be
 148   interesting for debugging, so that when a user send a verbose
 149   output we don't have to ask him for more details.  Display stderr
 150   output on the stderr file descriptor.  If some redirected command
 151   is likely to fail, and `set -e' is in effect, display its output
 152   even in the failure case, before exiting.
 153
 154   Use `Exit' rather than `exit' to abort a test.
 155
 156   Use `$PATH_SEPARATOR', not hard-coded `:', as the separator of
 157   PATH's entries.
 158
 159   It's more important to make sure that a feature works, than
 160   make sure that Automake's output looks correct.  It might look
 161   correct and still fail to work.  In other words, prefer
 162   running `make' over grepping `Makefile.in' (or do both).
 163
 164   If you run $AUTOMAKE or $AUTOCONF several times in the same test
 165   and change `configure.in' by the meantime, do
 166     rm -rf autom4te.cache
 167   before the following runs.  On fast machines the new `configure.in'
 168   could otherwise have the same timestamp as the old `autom4te.cache'.
 169   Alternatively, use `--force' for subsequent runs of the tools.
 170
 171   Use filenames with two consecutive spaces when testing that some
 172   code preserves filenames with spaces.  This will catch errors like
 173   `echo $filename | ...`.
 174
 175   Before commit: make sure the test is executable, add the tests to
 176   TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed,
 177   write a ChangeLog entry, send the diff to <automake-patches@gnu.org>.
 178
 179
 180 Do not
 181 ------
 182
 183   Do not test an Automake error with `$AUTOMAKE && Exit 1', or in three
 184   years we'll discover that this test failed for some other bogus reason.
 185   This happened many times.  Better use something like
 186      AUTOMAKE_fails
 187      grep 'expected diagnostic' stderr
 188   (Note this doesn't prevent the test from failing for another
 189   reason, but at least it makes sure the original error is still
 190   here.)
 191
 192   Do not override Makefile variables using make arguments, as in e.g.:
 193     $MAKE prefix=/opt install
 194   This is not portable for recursive targets (targets that call a
 195   sub-make may not pass `prefix=/opt' along).  Use the following
 196   instead:
 197     prefix=/opt $MAKE -e install