diff options
author | Stefano Lattarini <stefano.lattarini@gmail.com> | 2012-04-11 16:35:09 +0200 |
---|---|---|
committer | Stefano Lattarini <stefano.lattarini@gmail.com> | 2012-04-11 17:34:02 +0200 |
commit | 1490961b7bfcb4a5bba24925ff45e2ff32fa93f0 (patch) | |
tree | dde3c73b3665af9a666b920fe6c59a6fdf8b9333 /t/README | |
parent | 5edc5fc4b997d2748967a054638ca0190f10be51 (diff) | |
parent | e306fb5d1043c60b46128fb09ee54434340a0d42 (diff) | |
download | automake-1490961b7bfcb4a5bba24925ff45e2ff32fa93f0.tar.gz |
Merge branch 'master' into ng/master
* master:
vala tests: force the use of automatic dependency tracking
tests: avoid spurious failures in tests on C++ and lex
tests: avoid spurious failures with non-flex 'lex' programs and C++
tests: avoid a spurious failures for shells with busted 'set -e'
maint: simplify generation of files with @substed@ stuff
tests: remove redundant requirement
tests: make two test scripts executable
t/README: update w.r.t. recent overhaul (non-recursive build system)
docs: fix names of relevant test cases in comments
NEWS: automake build systems avoids make recursion
maint: no more make recursion in Automake's build system
tests: rename 'tests/' => 't/', '*.test' => '*.sh'
tests: remove recipes that run tests with 'prove'
tests: move most helper scripts and files into the 'ax' subdirectory
maint: remove most recursion in automake's own build system
tests: fix a spurious failures with non-GNU make
+ Extra non-trivial edits:
* Makefile.am: Remove new uses of 'AM_MAKEFLAGS' throughout.
(dist_automake_ac_DATA): Do not list 'm4/depout.m4' nor
'm4/make.m4'.
* syntax-checks.m4: Use '$(xdefs)' instead of hard-coding the
older paths of 'defs' and 'defs-static.in'. Use 't/README'
instead of 'tests/README'.
* t/instdir-no-empty.sh: Remove uses of 'AM_MAKEFLAGS'.
* tests/depcomp-recover.test: Renamed ...
* t/depcomp-recover.sh: ... to this.
* tests/gmake-vars.test: Renamed ...
* t/gmake-vars.sh: ... to this.
* tests/interp3.test: Renamed ...
* t/interp3.sh: ... to this.
* tests/objdir.test: Renamed ...
* t/objdir.sh: ... to this.
* tests/spy-vpath-rewrite.test: Renamed ...
* t/spy-vpath-rewrite.sh: ... to this.
* tests/vpath-rewrite.test: Renamed ...
* t/vpath-rewrite.sh: ... to this.
* tests/yacc-subobj-nodep.test: Renamed ...
* t/yacc-subobj-nodep.sh: ... to this.
* tests/depcomp-shuffle.sh: Renamed ...
* t/ax/depcomp-shuffle.sh: ... to this, and removed executable bit.
* t/depcomp-shuffle-sub-vpath.sh: Adjust.
* t/depcomp-shuffle-sub.sh: Likewise.
* t/depcomp-shuffle-vpath.sh: Likewise.
* t/depcomp-shuffle.sh: Likewise.
* gen-testsuite-part: Likewise.
* t/list-of-tests.mk: Do not list tests that had been already
removed from the Automake-NG testsuite. Take into account the
renames above.
Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>
Diffstat (limited to 't/README')
-rw-r--r-- | t/README | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/t/README b/t/README new file mode 100644 index 000000000..f1cdc5ff6 --- /dev/null +++ b/t/README @@ -0,0 +1,284 @@ + The Automake-NG test suite + + +User interface +============== + + +Running the tests +----------------- + + To run all tests: + + make -k check + + By default, verbose output of a test 't/foo.sh' or 't/foo.tap' is retained + in the log file 't/foo.log'. Also, a summary log is created in the file + 'test-suite.log' (in the top-level directory). + + You can use '-jN' for faster completion (it even helps on a uniprocessor + system, due to unavoidable sleep delays, as noted below): + + make -k -j4 + + To rerun only failed tests: + + make -k recheck + + To run only tests that are newer than their last results: + + make -k check RECHECK_LOGS= + + To run only selected tests: + + make -k check TESTS="t/foo.sh t/bar.tap" + + To run the tests in cross-compilation mode, you should first configure + the Automake-NG source tree to a cross-compilation setup. For example, + to run with a Linux-to-MinGW cross compiler, you will need something + like this: + + ./configure --host i586-mingw32msvc --build i686-pc-linux-gnu + + To avoid possible spurious error, you really have to *explicitly* specify + '--build' in addition to '--host'; the 'lib/config.guess' script can help + determine the correct value to pass to '--build'. + Then you can just run the testsuite in the usual way, and the test cases + using a compiler should automatically use a cross-compilation setup. + + +Interpretation +-------------- + + Successes: + PASS - success + XFAIL - expected failure + + Failures: + FAIL - failure + XPASS - unexpected success + + Other: + SKIP - skipped tests (third party tools not available) + ERROR - some unexpected error condition + + +About the tests +--------------- + + There are two kinds of tests in the Automake-NG testsuite (both + implemented as shell scripts). The scripts with the '.sh' suffix + are "simple" tests, their outcome completely determined by their + exit status. Those with the '.tap' suffix use the TAP protocol. + If you want to run a test by hand, you can do so directly if it is + a simple test: + + ./t/nogzip.sh + + (it will be verbose by default), while if it is a TAP test you can pass + it to your preferred TAP runner, as in e.g.: + + prove --verbose --merge ./t/add-missing.tap + + The tests can also be run directly in a VPATH build, as with: + + /path/to/srcdir/t/nogzip.sh + prove --verbose --merge /path/to/srcdir/t/add-missing.tap + + +Supported shells +---------------- + + By default, the tests are run by the $SHELL detected at configure + time. They also take care to re-execute themselves with that shell, + unless told not to. So, to run the tests with a different shell, say + '/path/to/another/sh', the user must use: + + AM_TESTS_REEXEC=no /path/to/another/sh ./t/foo.sh + AM_TESTS_REEXEC=no prove -v -e /path/to/another/sh ./t/bar.tap + + to run a test directly, and: + + make check LOG_COMPILER=/path/to/sh + + to run the test(s) through the makefile test driver. + + The test scripts are written with portability in mind, so that they + should run with any decent Bourne-compatible shell. + + However, some care must be used with Zsh, since, when not directly + started in Bourne-compatibility mode, it has some incompatibilities + in the handling of $0 which conflict with our usage. Our testsuite + can automatically work around these incompatibilities when a version + 4.3 or later of Zsh is used, but unfortunately not when an older + version of Zsh is used. Thus, if you want to run a test script, say + 'foo.sh', with Zsh 4.2, you *can't* simply do "zsh foo.sh", but + you *must* resort to: + + AM_TESTS_REEXEC=no zsh -o no_function_argzero foo.sh + + Note that this problem does not occur if Zsh is executed through + a symlink with a basename of 'sh', since in that case Zsh starts + in Bourne compatibility mode. So you should be perfectly safe + when /bin/sh is Zsh, even a it's version < 4.3. + + +Reporting failures +------------------ + + Send verbose output, i.e., the contents of test-suite.log, of failing + tests to <automake-ng@gnu.org>, along with the usual version numbers + (which Automake-NG, which Autoconf, which operating system, which make + version, which shell, etc.) + + + +Writing test cases +================== + + +Do +-- + + If you plan to fix a bug, write the test case first. This way you'll + make sure the test catches the bug, and that it succeeds once you have + fixed the bug. + + Add a copyright/license paragraph. + + Explain what the test does. + + Cite the PR number (if any), and the original reporter (if any), so + we can find or ask for information if needed. + + If a test checks examples or idioms given in the documentation, make + sure the documentation reference them appropriately in comments, as in: + @c Keep in sync with autodist-config-headers.sh + @example + ... + @end example + + Use "required=..." for required tools. Do not explicitly require + tools which can be taken for granted because they're listed in the + GNU Coding Standards (for example, 'gzip'). + + Include ./defs in every test script (see existing tests for examples + of how to do this). + + Use the 'skip_' function to skip tests, with a meaningful message if + possible. Where convenient, use the 'warn_' function to print generic + warnings, the 'fail_' function for test failures, and the 'fatal_' + function for hard errors. In case a hard error is due to a failed + set-up of a test scenario, you can use the 'framework_fail_' function + instead. + + For tests that use the 'parallel-tests' Automake-NG option, set the + shell variable 'am_parallel_tests' to "yes" before including ./defs. + For tests that are *not* meant to work with the 'parallel-tests' + Automake-NG option (these should be very very few), set the shell + variable 'am_parallel_tests' to "no" before including ./defs. + + Some tests in the Automake-NG testsuite are auto-generated; those tests + might have custom extensions, but their basename (that is, with such + extension stripped) is expected to end with "-w" string, optionally + followed by decimal digits. For example, the name of a valid + auto-generated test can be 'color-w.sh' or 'tap-signal-w09.tap'. + Please don't name hand-written tests in a way that could cause them + to be confused with auto-generated tests; for example, 'u-v-w.sh' + or 'option-w0.tap' are *not* valid name for hand-written tests. + + ./defs brings in some commonly required files, and sets a skeleton + configure.ac. If possible, append to this file. In some cases + you'll have to overwrite it, but this should be the exception. Note + that configure.ac registers Makefile.in but do not output anything by + default. If you need ./configure to create Makefile, append AC_OUTPUT + to configure.ac. In case you don't want ./defs to pre-populate your + test directory (which is a rare occurrence), set the 'am_create_testdir' + shell variable to "empty" before sourcing ./defs. + + By default, the testcases are run with the errexit shell flag on, + to make it easier to catch failures you might not have thought of. + If this is undesirable in some testcase, you can use "set +e" to + disable the errexit flag (but please do so only if you have a very + good reason). + + End the test script with a ":" or "Exit 0". Otherwise, when somebody + changes the test by adding a failing command after the last command, + the test will spuriously fail because $? is nonzero at the end. Note + that this is relevant even if the errexit shell flag is on, in case + the test contains commands like "grep ... Makefile.in && Exit 1" (and + there are indeed a lot of such tests). + + Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER, + $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding + commands. + + Use $sleep when you have to make sure that some file is newer + than another. + + Use cat or grep or similar commands to display (part of) files that + may be interesting for debugging, so that when a user send a verbose + output we don't have to ask him for more details. Display stderr + output on the stderr file descriptor. If some redirected command is + likely to fail, display its output even in the failure case, before + exiting. + + Use 'Exit' rather than 'exit' to abort for leave early from a test + case. + + Use '$PATH_SEPARATOR', not hard-coded ':', as the separator of + PATH's entries. + + It's more important to make sure that a feature works, than make sure + that the output of Automake-NG looks correct. It might look correct + and still fail to work. In other words, prefer running 'make' over + grepping Makefile.in (or do both). + + If you run $ACLOCAL, $AUTOMAKE or $AUTOCONF several times in the + same test and change configure.ac by the meantime, do + rm -rf autom4te*.cache + before the following runs. On fast machines the new configure.ac + could otherwise have the same timestamp as the old autom4te.cache. + + Use filenames with two consecutive spaces when testing that some + code preserves filenames with spaces. This will catch errors like + `echo $filename | ...`. + + Make sure your test script can be used to faithfully check an + installed version of Automake-ng (as with "make installcheck"). For + example, if you need to copy or grep an Automake-ng provided script, + do not assume that they can be found in the '$top_srcdir/lib' + directory, but use '$am_scriptdir' instead. The complete list of + such "$am_...dir" variables can be found in the 'defs-static.in' + file. + + When writing input for lex, include the following in the definitions + section: + %{ + #define YY_NO_UNISTD_H 1 + %} + to accommodate non-ANSI systems, since GNU flex generates code that + includes unistd.h otherwise. Also add: + int isatty (int fd) { return 0; } + to the definitions section if the generated code is to be compiled + by a C++ compiler, for similar reasons (i.e., the isatty(3) function + from that same unistd.h header would be required otherwise). + + Before commit: make sure the test is executable, add the tests to + TESTS in Makefile.am, add it to XFAIL_TESTS in addition if needed, + write a ChangeLog entry, send the diff to <automake-ng@gnu.org>. + + +Do not +------ + + Do not test an Automake-NG error with "$AUTOMAKE && Exit 1", or in + three years we'll discover that this test failed for some other bogus + reason. This happened many times. Better use something like + + AUTOMAKE_fails + grep 'expected diagnostic' stderr + + (Note this doesn't prevent the test from failing for another + reason, but at least it makes sure the original error is still + here.) |