tests/README

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