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 Interpretation
  18 --------------
  19
  20   Successes:
  21     PASS  - success
  22     XFAIL - expected failure
  23
  24   Failures:
  25     FAIL  - failure
  26     XPASS - unexpected success
  27
  28   Other:
  29     SKIP  - skipped tests (third party tools not available)
  30
  31
  32 Getting details from failures
  33 -----------------------------
  34
  35   Each test is a script.  In a non-VPATH build you can run them
  36   directly, they will be verbose.  By default, verbose output of
  37   a test foo.test is retained in the log file foo.log.  A summary
  38   log is created in the file test-suite.log.
  39
  40   You can limit the set of files using the TESTS variable, and
  41   enable detailed test output at the end of the test run with the
  42   VERBOSE variable:
  43
  44     env VERBOSE=x TESTS='first.test second.test ...' make -e check
  45
  46
  47 Reporting failures
  48 ------------------
  49
  50   Send verbose output, i.e., the contents of test-suite.log, of failing
  51   tests to <bug-automake@gnu.org>, along with the usual version numbers
  52   (which Automake, which Autoconf, which operating system, which make
  53   version, which shell, etc.)
  54
  55
  56
  57 Writing test cases
  58 ==================
  59
  60
  61 Do
  62 --
  63
  64   If you plan to fix a bug, write the test case first.  This way you'll
  65   make sure the test catches the bug, and that it succeeds once you have
  66   fixed the bug.
  67
  68   Add a copyright/license paragraph.
  69
  70   Explain what the test does.
  71
  72   Cite the PR number (if any), and the original reporter (if any), so
  73   we can find or ask for information if needed.
  74
  75   Use `required=...' for required tools.
  76
  77   Include ./defs (see other tests) for normal tests, ./defs-p for tests
  78   that use the `parallel-tests' option.  For the latter, use a name that
  79   ends in `-p.test' and does not clash with any generated tests in the
  80   suite.
  81
  82   Use `set -e' to catch failures you might not have thought of.
  83
  84   ./defs sets a skeleton configure.in.  If possible, append to this
  85   file.  In some cases you'll have to overwrite it, but this should
  86   be the exception.  Note that configure.in registers Makefile.in
  87   but do not output anything by default.  If you need ./configure
  88   to create Makefile, append AC_OUTPUT to configure.in.
  89
  90   Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
  91   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
  92   commands.
  93
  94   Use $sleep when you have to make sure that some file is newer
  95   than another.
  96
  97   Use `cat' or `grep' to display (part of) files that may be
  98   interesting for debugging, so that when a user send a verbose
  99   output we don't have to ask him for more details.  Display stderr
 100   output on the stderr file descriptor.  If some redirected command
 101   is likely to fail, and `set -e' is in effect, display its output
 102   even in the failure case, before exiting.
 103
 104   Use `Exit' rather than `exit' to abort a test.
 105
 106   It's more important to make sure that a feature works, than
 107   make sure that Automake's output looks correct.  It might look
 108   correct and still fail to work.  In other words, prefer
 109   running `make' over grepping `Makefile.in' (or do both).
 110
 111   If you run $AUTOMAKE or $AUTOCONF several times in the same test
 112   and change `configure.in' by the meantime, do
 113     rm -rf autom4te.cache
 114   before the following runs.  On fast machines the new `configure.in'
 115   could otherwise have the same timestamp as the old `autom4te.cache'.
 116   Alternatively, use `--force' for subsequent runs of the tools.
 117
 118   Use filenames with two consecutive spaces when testing that some
 119   code preserves filenames with spaces.  This will catch errors like
 120   `echo $filename | ...`.
 121
 122   Before commit: make sure the test is executable, add the tests to
 123   TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed,
 124   write a ChangeLog entry, send the diff to <automake-patches@gnu.org>.
 125
 126
 127 Do not
 128 ------
 129
 130   Do not test an Automake error with `$AUTOMAKE && Exit 1', or in three
 131   years we'll discover that this test failed for some other bogus reason.
 132   This happened many times.  Better use something like
 133      AUTOMAKE_fails
 134      grep 'expected diagnostic' stderr
 135   (Note this doesn't prevent the test from failing for another
 136   reason, but at least it makes sure the original error is still
 137   here.)
 138
 139   Do not override Makefile variables using make arguments, as in
 140     $MAKE ANSI2KNR=./ansi2knr U=_ all
 141   this is not portable for recursive targets (targets that
 142   call a sub-make may not pass `ANSI2KNR=./ansi2knr U=_' along).
 143   Use the following instead.
 144     ANSI2KNR=./ansi2knr U=_ $MAKE -e all
 145
 146   Do not send a test case without signing a copyright disclaimer.
 147   See http://sources.redhat.com/automake/contribute.html or
 148   ask <automake@gnu.org> for details.