gnu/dist/autoconf/tests/README

   1                                                         -*- outline -*-
   2
   3 This directory holds the M4sugar, M4sh and Autoconf test suites.
   4
   5
   6 Here are a few rules on how to write tests.
   7
   8 * Order of the tests
   9
  10 It is extremely important to pay attention to the order of the tests.
  11 There are basically two philosophies: (i) test earlier the most
  12 critical features (hence hurried users will at least check those), or
  13 (ii) test earlier the primitives.
  14
  15 For having tried both, I definitely recommend (ii).  In practice users
  16 will run the whole test suite even if it's long.  And if they don't,
  17 there will be enough other users who will do the job.
  18
  19 But also in practice some problems in the core of project can be
  20 responsible for an incredible number of failures.  Then the problems
  21 at the origin will be hidden by the consequences.  If dependencies are
  22 properly ordered in the test suite (test features which depend upon
  23 other features *after* having checked the latter), basically you'll
  24 just have to pay attention to the first failures.  BTW, it also makes
  25 `./testsuite -e' much more useful.
  26
  27
  28 * Write tests!
  29
  30 Don't let you be bitten three times by the same dog!  When you spent a
  31 significant amount of time tracking the failure of feature in some
  32 more primitive problem, immediately write a test for the latter.
  33
  34 If you track down several bugs down to the same origin, write a test
  35 especially for it.
  36
  37 Of course in both cases, more primitive tests will be run beforehand.
  38 Write your test and have it failed before your fixing, and succeeding
  39 after.  This usually means having at hand two copies of the source
  40 tree, one running the test suite to have it fail, and the other to
  41 have the same testsuite succeed.
  42
  43
  44 * Autoconf
  45
  46 ** Use of `exit'
  47 Don't directly `exit 1' or `exit 77', rather use `AC_MSG_ERROR'.
  48 First of all because when we have to read the test suite logs we are
  49 happy to know why `configure' exited thanks to the error
  50 message. Secondly, because `configure' traps the `exit' and pretty
  51 many shells fail to set $? to 77 when trapping `exit 77'.  This
  52 results in the test suite not being able to check the exit status.
  53
  54 ** AC_MSG_ERROR
  55 Of course, since macro names are forbidden in `configure', if you
  56 really want to mention the macro name, you'll have to do without
  57 including `A?_' in the output.