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   Use `required=...' for required tools.
  97
  98   Include ./defs in every test script (see existing tests for examples
  99   of how to do this).
 100
 101   For tests that use the `parallel-tests' Automake option, set the shell
 102   variable `parallel_tests' to "yes" before including ./defs.  Also,
 103   use for them a name that ends in `-p.test' and does not clash with any
 104   generated tests in the suite.
 105
 106   ./defs sets a skeleton configure.in.  If possible, append to this
 107   file.  In some cases you'll have to overwrite it, but this should
 108   be the exception.  Note that configure.in registers Makefile.in
 109   but do not output anything by default.  If you need ./configure
 110   to create Makefile, append AC_OUTPUT to configure.in.
 111
 112   Use `set -e' to catch failures you might not have thought of.
 113
 114   End the test script with a `:' or `Exit 0'.  Otherwise, when somebody
 115   changes the test by adding a failing command after the last command,
 116   the test will spuriously fail because $? is nonzero at the end.
 117   Note that this is relevant also for tests using `set -e', if they
 118   contain commands like "grep ... Makefile.in && Exit 1" (and there
 119   are indeed a lot of such tests).
 120
 121   Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
 122   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
 123   commands.
 124
 125   Use $sleep when you have to make sure that some file is newer
 126   than another.
 127
 128   Use `cat' or `grep' to display (part of) files that may be
 129   interesting for debugging, so that when a user send a verbose
 130   output we don't have to ask him for more details.  Display stderr
 131   output on the stderr file descriptor.  If some redirected command
 132   is likely to fail, and `set -e' is in effect, display its output
 133   even in the failure case, before exiting.
 134
 135   Use `Exit' rather than `exit' to abort a test.
 136
 137   It's more important to make sure that a feature works, than
 138   make sure that Automake's output looks correct.  It might look
 139   correct and still fail to work.  In other words, prefer
 140   running `make' over grepping `Makefile.in' (or do both).
 141
 142   If you run $AUTOMAKE or $AUTOCONF several times in the same test
 143   and change `configure.in' by the meantime, do
 144     rm -rf autom4te.cache
 145   before the following runs.  On fast machines the new `configure.in'
 146   could otherwise have the same timestamp as the old `autom4te.cache'.
 147   Alternatively, use `--force' for subsequent runs of the tools.
 148
 149   Use filenames with two consecutive spaces when testing that some
 150   code preserves filenames with spaces.  This will catch errors like
 151   `echo $filename | ...`.
 152
 153   Before commit: make sure the test is executable, add the tests to
 154   TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed,
 155   write a ChangeLog entry, send the diff to <automake-patches@gnu.org>.
 156
 157
 158 Do not
 159 ------
 160
 161   Do not test an Automake error with `$AUTOMAKE && Exit 1', or in three
 162   years we'll discover that this test failed for some other bogus reason.
 163   This happened many times.  Better use something like
 164      AUTOMAKE_fails
 165      grep 'expected diagnostic' stderr
 166   (Note this doesn't prevent the test from failing for another
 167   reason, but at least it makes sure the original error is still
 168   here.)
 169
 170   Do not override Makefile variables using make arguments, as in
 171     $MAKE ANSI2KNR=./ansi2knr U=_ all
 172   this is not portable for recursive targets (targets that
 173   call a sub-make may not pass `ANSI2KNR=./ansi2knr U=_' along).
 174   Use the following instead.
 175     ANSI2KNR=./ansi2knr U=_ $MAKE -e all
 176
 177   Do not send a test case without signing a copyright disclaimer.
 178   See http://sources.redhat.com/automake/contribute.html or
 179   ask <automake@gnu.org> for details.