t/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   By default, verbose output of a test 't/foo.sh' or 't/foo.tap' is retained
  16   in the log file 't/foo.log'.  Also, a summary log is created in the file
  17   'test-suite.log' (in the top-level directory).
  18
  19   You can use '-jN' for faster completion (it even helps on a uniprocessor
  20   system, due to unavoidable sleep delays, as noted below):
  21
  22     make -k -j4
  23
  24   To rerun only failed tests:
  25
  26     make -k recheck
  27
  28   To run only tests that are newer than their last results:
  29
  30     make -k check RECHECK_LOGS=
  31
  32   To run only selected tests:
  33
  34     make -k check TESTS="t/foo.sh t/bar.tap"           (GNU make)
  35     env TESTS="t/foo.sh t/bar.tap" make -e -k check    (non-GNU make)
  36
  37  To run the tests in cross-compilation mode, you should first configure
  38  the automake source tree to a cross-compilation setup.  For example, to
  39  run with a Linux-to-MinGW cross compiler, you will need something like
  40  this:
  41
  42    ./configure --host i586-mingw32msvc --build i686-pc-linux-gnu
  43
  44  To avoid possible spurious error, you really have to *explicitly* specify
  45  '--build' in addition to '--host'; the 'lib/config.guess' script can help
  46  determine the correct value to pass to '--build'.
  47  Then you can just run the testsuite in the usual way, and the test cases
  48  using a compiler should automatically use a cross-compilation setup.
  49
  50
  51 Interpretation
  52 --------------
  53
  54   Successes:
  55     PASS  - success
  56     XFAIL - expected failure
  57
  58   Failures:
  59     FAIL  - failure
  60     XPASS - unexpected success
  61
  62   Other:
  63     SKIP  - skipped tests (third party tools not available)
  64     ERROR - some unexpected error condition
  65
  66
  67 About the tests
  68 ---------------
  69
  70   There are two kinds of tests in the Automake testsuite (both implemented
  71   as shell scripts).  The scripts with the '.sh' suffix are "simple"
  72   tests, their outcome completely determined by their exit status.  Those
  73   with the '.tap' suffix use the TAP protocol.  If you want to run a test
  74   by hand, you can do so directly if it is a simple test:
  75
  76     ./t/nogzip.sh
  77
  78   (it will be verbose by default), while if it is a TAP test you can pass
  79   it to your preferred TAP runner, as in e.g.:
  80
  81     prove --verbose --merge ./t/add-missing.tap
  82
  83   The tests can also be run directly in a VPATH build, as with:
  84
  85     /path/to/srcdir/t/nogzip.sh
  86     prove --verbose --merge /path/to/srcdir/t/add-missing.tap
  87
  88
  89 Supported shells
  90 ----------------
  91
  92   By default, the tests are run by the $SHELL detected at configure
  93   time.  They also take care to re-execute themselves with that shell,
  94   unless told not to.  So, to run the tests with a different shell, say
  95   '/path/to/another/sh', the user must use:
  96
  97     AM_TESTS_REEXEC=no /path/to/another/sh ./t/foo.sh
  98     AM_TESTS_REEXEC=no prove -v -e /path/to/another/sh ./t/bar.tap
  99
 100   to run a test directly, and:
 101
 102     make check LOG_COMPILER=/path/to/sh         (GNU make)
 103     LOG_COMPILER=/path/to/sh make -e check      (non-GNU make)
 104
 105   to run the test(s) through the makefile test driver.
 106
 107   The test scripts are written with portability in mind, so that they
 108   should run with any decent Bourne-compatible shell.
 109
 110   However, some care must be used with Zsh, since, when not directly
 111   started in Bourne-compatibility mode, it has some incompatibilities
 112   in the handling of $0 which conflict with our usage.  Our testsuite
 113   can automatically work around these incompatibilities when a version
 114   4.3 or later of Zsh is used, but unfortunately not when an older
 115   version of Zsh is used.  Thus, if you want to run a test script, say
 116   'foo.sh', with Zsh 4.2, you *can't* simply do "zsh foo.sh", but
 117   you *must* resort to:
 118
 119     AM_TESTS_REEXEC=no zsh -o no_function_argzero foo.sh
 120
 121   Note that this problem does not occur if Zsh is executed through
 122   a symlink with a basename of 'sh', since in that case Zsh starts
 123   in Bourne compatibility mode.  So you should be perfectly safe
 124   when /bin/sh is Zsh, even a it's version < 4.3.
 125
 126
 127 Reporting failures
 128 ------------------
 129
 130   Send verbose output, i.e., the contents of test-suite.log, of failing
 131   tests to <bug-automake@gnu.org>, along with the usual version numbers
 132   (which Automake, which Autoconf, which operating system, which make
 133   version, which shell, etc.)
 134
 135
 136
 137 Writing test cases
 138 ==================
 139
 140
 141 Do
 142 --
 143
 144   If you plan to fix a bug, write the test case first.  This way you'll
 145   make sure the test catches the bug, and that it succeeds once you have
 146   fixed the bug.
 147
 148   Add a copyright/license paragraph.
 149
 150   Explain what the test does.
 151
 152   Cite the PR number (if any), and the original reporter (if any), so
 153   we can find or ask for information if needed.
 154
 155   If a test checks examples or idioms given in the documentation, make
 156   sure the documentation reference them appropriately in comments, as in:
 157     @c Keep in sync with autodist-config-headers.sh
 158     @example
 159     ...
 160     @end example
 161
 162   Use "required=..." for required tools.  Do not explicitly require
 163   tools which can be taken for granted because they're listed in the
 164   GNU Coding Standards (for example, 'gzip').
 165
 166   Include ./defs in every test script (see existing tests for examples
 167   of how to do this).
 168
 169   Use the 'skip_' function to skip tests, with a meaningful message if
 170   possible.  Where convenient, use the 'warn_' function to print generic
 171   warnings, the 'fail_' function for test failures, and the 'fatal_'
 172   function for hard errors.  In case a hard error is due to a failed
 173   set-up of a test scenario, you can use the 'framework_fail_' function
 174   instead.
 175
 176   For tests that use the 'parallel-tests' Automake option, set the shell
 177   variable 'am_parallel_tests' to "yes" before including ./defs.  For
 178   tests that are *not* meant to work with the 'parallel-tests' Automake
 179   option (these should be very very few), set the shell variable
 180   'am_parallel_tests' to "no" before including ./defs.
 181
 182   Some tests in the Automake testsuite are auto-generated; those tests
 183   might have custom extensions, but their basename (that is, with such
 184   extension stripped) is expected to end with "-w" string, optionally
 185   followed by decimal digits.  For example, the name of a valid
 186   auto-generated test can be 'color-w.sh' or 'tap-signal-w09.tap'.
 187   Please don't name hand-written tests in a way that could cause them
 188   to be confused with auto-generated tests; for example, 'u-v-w.sh'
 189   or 'option-w0.tap' are *not* valid name for hand-written tests.
 190
 191   ./defs brings in some commonly required files, and sets a skeleton
 192   configure.ac.  If possible, append to this file.  In some cases
 193   you'll have to overwrite it, but this should be the exception.  Note
 194   that configure.ac registers Makefile.in but do not output anything by
 195   default.  If you need ./configure to create Makefile, append AC_OUTPUT
 196   to configure.ac.  In case you don't want ./defs to pre-populate your
 197   test directory (which is a rare occurrence), set the 'am_create_testdir'
 198   shell variable to "empty" before sourcing ./defs.
 199
 200   By default, the testcases are run with the errexit shell flag on,
 201   to make it easier to catch failures you might not have thought of.
 202   If  this is undesirable in some testcase, you can use "set +e" to
 203   disable the errexit flag (but please do so only if you have a very
 204   good reason).
 205
 206   End the test script with a ":" or "Exit 0".  Otherwise, when somebody
 207   changes the test by adding a failing command after the last command,
 208   the test will spuriously fail because $? is nonzero at the end.  Note
 209   that this is relevant even if the errexit shell flag is on, in case
 210   the test contains commands like "grep ... Makefile.in && Exit 1" (and
 211   there are indeed a lot of such tests).
 212
 213   Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
 214   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
 215   commands.
 216
 217   Use $sleep when you have to make sure that some file is newer
 218   than another.
 219
 220   Use cat or grep or similar commands to display (part of) files that
 221   may be interesting for debugging, so that when a user send a verbose
 222   output we don't have to ask him for more details.  Display stderr
 223   output on the stderr file descriptor.  If some redirected command is
 224   likely to fail, display its output even in the failure case, before
 225   exiting.
 226
 227   Use 'Exit' rather than 'exit' to abort for leave early from a test
 228   case.
 229
 230   Use '$PATH_SEPARATOR', not hard-coded ':', as the separator of
 231   PATH's entries.
 232
 233   It's more important to make sure that a feature works, than make
 234   sure that Automake's output looks correct.  It might look correct
 235   and still fail to work.  In other words, prefer running 'make' over
 236   grepping Makefile.in (or do both).
 237
 238   If you run $ACLOCAL, $AUTOMAKE or $AUTOCONF several times in the
 239   same test and change configure.ac by the meantime, do
 240     rm -rf autom4te*.cache
 241   before the following runs.  On fast machines the new configure.ac
 242   could otherwise have the same timestamp as the old autom4te.cache.
 243
 244   Use filenames with two consecutive spaces when testing that some
 245   code preserves filenames with spaces.  This will catch errors like
 246   `echo $filename | ...`.
 247
 248   Make sure your test script can be used to faithfully check an
 249   installed version of automake (as with "make installcheck").  For
 250   example, if you need to copy or grep an automake-provided script,
 251   do not assume that they can be found in the '$top_srcdir/lib'
 252   directory, but use '$am_scriptdir' instead.  The complete list of
 253   such "$am_...dir" variables can be found in the 'defs-static.in'
 254   file.
 255
 256   When writing input for lex, include the following in the definitions
 257   section:
 258     %{
 259     #define YY_NO_UNISTD_H 1
 260     %}
 261   to accommodate non-ANSI systems, since GNU flex generates code that
 262   includes unistd.h otherwise.  Also add:
 263     int isatty (int fd) { return 0; }
 264   to the definitions section if the generated code is to be compiled
 265   by a C++ compiler, for similar reasons (i.e., the isatty(3) function
 266   from that same unistd.h header would be required otherwise).
 267
 268   Before commit: make sure the test is executable, add the tests to
 269   TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed,
 270   write a ChangeLog entry, send the diff to <automake-patches@gnu.org>.
 271
 272
 273 Do not
 274 ------
 275
 276   Do not test an Automake error with "$AUTOMAKE && Exit 1", or in three
 277   years we'll discover that this test failed for some other bogus reason.
 278   This happened many times.  Better use something like
 279      AUTOMAKE_fails
 280      grep 'expected diagnostic' stderr
 281   (Note this doesn't prevent the test from failing for another reason,
 282   but at least it makes sure the original error is still here).
 283
 284   Do not override Makefile variables using make arguments, as in e.g.:
 285     $MAKE prefix=/opt install
 286   This is not portable for recursive targets (targets that call a
 287   sub-make may not pass "prefix=/opt" along).  Use the following
 288   instead:
 289     prefix=/opt $MAKE -e install