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.  However, it is
 109   worth nothing that older versions of Zsh (pre-4.3) exhibited several
 110   bugs and incompatibilities with our uses, and are thus not supported
 111   for running Automake's test scripts.
 112
 113
 114 Reporting failures
 115 ------------------
 116
 117   Send verbose output, i.e., the contents of test-suite.log, of failing
 118   tests to <bug-automake@gnu.org>, along with the usual version numbers
 119   (which Automake, which Autoconf, which operating system, which make
 120   version, which shell, etc.)
 121
 122
 123
 124 Writing test cases
 125 ==================
 126
 127 * If you plan to fix a bug, write the test case first.  This way you'll
 128   make sure the test catches the bug, and that it succeeds once you have
 129   fixed the bug.
 130
 131 * Add a copyright/license paragraph.
 132
 133 * Explain what the test does, i.e., which features it checks, which
 134   invariants it verifies, or what bugs/issues it guard against.
 135
 136 * Cite the PR number (if any), and the original reporter (if any), so
 137   we can find or ask for information if needed.
 138
 139 * If a test checks examples or idioms given in the documentation, make
 140   sure the documentation reference them appropriately in comments, as
 141   with:
 142
 143     @c Keep in sync with autodist-config-headers.sh
 144     @example
 145     ...
 146     @end example
 147
 148 * Use "required=..." for required tools.  Do not explicitly require
 149   tools which can be taken for granted because they're listed in the
 150   GNU Coding Standards (for example, 'gzip').
 151
 152 * Include ./defs in every test script (see existing tests for examples
 153   of how to do this).
 154
 155 * Use the 'skip_' function to skip tests, with a meaningful message if
 156   possible.  Where convenient, use the 'warn_' function to print generic
 157   warnings, the 'fail_' function for test failures, and the 'fatal_'
 158   function for hard errors.  In case a hard error is due to a failed
 159   set-up of a test scenario, you can use the 'framework_fail_' function
 160   instead.
 161
 162 * For those tests checking the Automake-provided test harnesses that
 163   are expected to work also when the 'serial-tests' Automake option
 164   is used (thus causing the serial testsuite harness to be used in the
 165   generated Makefile), place a line containing "try-with-serial-tests"
 166   somewhere in the file (usually in a comment).
 167   That will ensure that the 'gen-testsuite-part' script generates a
 168   sibling of that test which uses the serial harness instead of the
 169   parallel one.  For those tests that are *not* meant to work with the
 170   parallel testsuite harness at all (these should be very very few),
 171   set the shell variable 'am_serial_tests' to "yes" before including
 172   ./defs.
 173
 174 * Some tests in the Automake testsuite are auto-generated; those tests
 175   might have custom extensions, but their basename (that is, with such
 176   extension stripped) is expected to end with "-w" string, optionally
 177   followed by decimal digits.  For example, the name of a valid
 178   auto-generated test can be 'color-w.sh' or 'tap-signal-w09.tap'.
 179   Please don't name hand-written tests in a way that could cause them
 180   to be confused with auto-generated tests; for example, 'u-v-w.sh'
 181   or 'option-w0.tap' are *not* valid name for hand-written tests.
 182
 183 * ./defs brings in some commonly required files, and sets a skeleton
 184   configure.ac.  If possible, append to this file.  In some cases
 185   you'll have to overwrite it, but this should be the exception.  Note
 186   that configure.ac registers Makefile.in but do not output anything by
 187   default.  If you need ./configure to create Makefile, append AC_OUTPUT
 188   to configure.ac.  In case you don't want ./defs to pre-populate your
 189   test directory (which is a rare occurrence), set the 'am_create_testdir'
 190   shell variable to "empty" before sourcing ./defs.
 191
 192 * By default, the testcases are run with the errexit shell flag on,
 193   to make it easier to catch failures you might not have thought of.
 194   If  this is undesirable in some testcase, you can use "set +e" to
 195   disable the errexit flag (but please do so only if you have a very
 196   good reason).
 197
 198 * End the test script with a ':' command.  Otherwise, when somebody
 199   changes the test by adding a failing command after the last command,
 200   the test will spuriously fail because '$?' is nonzero at the end.
 201   Note that this is relevant even if the errexit shell flag is on, in
 202   case the test contains commands like "grep ... Makefile.in && exit 1"
 203   (and there are indeed a lot of such tests).
 204
 205 * Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
 206   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
 207   commands.
 208
 209 * Use '$sleep' when you have to make sure that some file is newer
 210   than another.
 211
 212 * Use cat or grep or similar commands to display (part of) files that
 213   may be interesting for debugging, so that when a user send a verbose
 214   output we don't have to ask him for more details.  Display stderr
 215   output on the stderr file descriptor.  If some redirected command is
 216   likely to fail, display its output even in the failure case, before
 217   exiting.
 218
 219 * Use '$PATH_SEPARATOR', not hard-coded ':', as the separator of
 220   PATH's entries.
 221
 222 * It's more important to make sure that a feature works, than make
 223   sure that Automake's output looks correct.  It might look correct
 224   and still fail to work.  In other words, prefer running 'make' over
 225   grepping Makefile.in (or do both).
 226
 227 * If you run $ACLOCAL, $AUTOMAKE or $AUTOCONF several times in the
 228   same test and change configure.ac by the meantime, do
 229
 230     rm -rf autom4te*.cache
 231
 232   before the following runs.  On fast machines the new configure.ac
 233   could otherwise have the same timestamp as the old autom4te.cache.
 234
 235 * Use filenames with two consecutive spaces when testing that some
 236   code preserves filenames with spaces.  This will catch errors like
 237   `echo $filename | ...`.
 238
 239 * Make sure your test script can be used to faithfully check an
 240   installed version of automake (as with "make installcheck").  For
 241   example, if you need to copy or grep an automake-provided script,
 242   do not assume that they can be found in the '$top_srcdir/lib'
 243   directory, but use '$am_scriptdir' instead.  The complete list of
 244   such "$am_...dir" variables can be found in the 'defs-static.in'
 245   file.
 246
 247 * When writing input for lex, include the following in the definitions
 248   section:
 249
 250     %{
 251     #define YY_NO_UNISTD_H 1
 252     %}
 253
 254   to accommodate non-ANSI systems, since GNU flex generates code that
 255   includes unistd.h otherwise.  Also add:
 256
 257     int isatty (int fd) { return 0; }
 258
 259   to the definitions section if the generated code is to be compiled
 260   by a C++ compiler, for similar reasons (i.e., the isatty(3) function
 261   from that same unistd.h header would be required otherwise).
 262
 263 * Before commit: make sure the test is executable, add the tests to
 264   TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed,
 265   write a ChangeLog entry, send the diff to <automake-patches@gnu.org>.
 266
 267 * In test scripts, prefer using POSIX constructs over their old
 268   Bourne-only equivalents:
 269
 270     - use $(...), not `...`, for command substitution;
 271     - use $((...)), not `expr ...`, for arithmetic processing;
 272     - liberally use '!' to invert the exit status of a command, e.g.,
 273       in idioms like "if ! CMD; then ...", instead of relying on clumsy
 274       paraphrases like "if CMD; then :; else ...".
 275     - prefer use of ${param%pattern} and ${param#pattern} parameter
 276       expansions over processing by 'sed' or 'expr'.
 277
 278 * Note however that, when writing Makefile recipes or shell code in a
 279   configure.ac, you should still use `...` instead, because the Autoconf
 280   generated configure scripts do not ensure they will find a truly POSIX
 281   shell (even though they will prefer and use it *if* it's found).
 282
 283 * Do not test an Automake error with "$AUTOMAKE && exit 1", or in three
 284   years we'll discover that this test failed for some other bogus reason.
 285   This happened many times.  Better use something like
 286
 287      AUTOMAKE_fails
 288      grep 'expected diagnostic' stderr
 289
 290   Note this doesn't prevent the test from failing for another reason,
 291   but at least it makes sure the original error is still here.
 292
 293 * Do not override Makefile variables using make arguments, as in e.g.:
 294
 295     $MAKE prefix=/opt install
 296
 297   This is not portable for recursive targets (targets that call a
 298   sub-make may not pass "prefix=/opt" along).  Use the following
 299   instead:
 300
 301     prefix=/opt $MAKE -e install