t/README

   1 Test Files
   2 ==========
   3
   4 All tests are shell scripts and must be named to
   5 match:
   6
   7     t[0-9][0-9][0-9][0-9]-*.sh
   8
   9 They must output TAP (Test Anything Protocol) compliant
  10 format.  In particular, only version 12 format is supported,
  11 NOT version 13.  See `perldoc Test::Harness::TAP` for extensive
  12 details on the format.  A more formal grammar can be found
  13 in `perldoc TAP::Parser::Grammar` if desired.  See also
  14 `perldoc TAP::Parser` and <http://testanything.org> as well for
  15 copies of the specification.
  16
  17 All tests are run with the current directory set to the same
  18 directory as the directory containing the test file itself.
  19
  20
  21 -------------------------
  22 Test Naming and Numbering
  23 -------------------------
  24
  25 All the test scripts are named like so:
  26
  27     tNNNN-command-more-info.sh
  28
  29 Where `NNNN` is a 4-digit, 0-padded decimal number.
  30
  31 The first (i.e. leftmost) digit should indicate the category of the test as
  32 follows:
  33
  34   0. the testing framework itself and universal stuff
  35   1. basic fundamental commands and options (e.g. help, status, --top-bases)
  36   2. creation and deletion of tg branches and dependencies and hooks
  37   3. graph navigation commands (e.g. prev, next, checkout)
  38   4. informational and introspection commands (e.g. summary, info, base)
  39   5. update command
  40   6. tag and revert
  41   7. remote and push
  42   8. import and export
  43   9. shortcut and utility commands (e.g. files, log, mail, patch, rebase)
  44
  45 The second digit should indicate the command within that group.  In other words
  46 if the second digit is "3" then all tests numbered 13NN should be testing the
  47 same command.
  48
  49 Generally a given command should have all its tests in the same family.
  50
  51 The third digit should be used for grouping tests of the same or related
  52 options of a command when the command supports a lot of options or may instead
  53 indicate a command "mode" that's being tested (e.g. `tg tag` has several
  54 different command modes).
  55
  56
  57 ------------
  58 Test Library
  59 ------------
  60
  61 A testing library is available to facilitate writing tests.
  62
  63 It should be sourced by test scripts wanting to use it AFTER
  64 setting the "test_description" variable and then calling the
  65 provided functions to produce TAP output like so:
  66
  67     test_description='title of test goes here
  68
  69     And any more lines go here much like a standard Git
  70     checkin comment although there's no requirement that
  71     the description follow any partiuclar layout.  It's
  72     only used by the -h|--help functionality.
  73     '
  74
  75     . ./test-lib.sh
  76
  77     test_expect_success 'small test' '
  78         # do some testing
  79         ...
  80     '
  81
  82     ...
  83
  84     test_done
  85
  86 For more detailed information on how to use the test-lib.sh
  87 testing library see the README-TESTLIB and README-WRITING-TESTS
  88 files.
  89
  90
  91 ----------------------
  92 TAP - A Quick Overview
  93 ----------------------
  94
  95 Only output to STDOUT is examined and
  96 must consist of one of four kinds of lines:
  97
  98   1) A test plan line matching either:
  99      a) "^1..n$" where n is a positive integer
 100      b) "^1..0(?![0-9]).*?#\s*(?i)SKIP\S*\s+(.*)$" where $1 is skip reason
 101         (this format is only valid if there are no test lines)
 102      There MUST BE EXACTLY ONE test plan line and it must appear either
 103      BEFORE ALL or AFTER ALL of the test lines.  For example, the following
 104      line plans four tests:
 105          1..4
 106
 107   2) Test lines which must either be ALL BEFORE or ALL AFTER the test plan line
 108      a) "^ok(?:\s+$stuff?)?$" test succeeds
 109      b) "^not ok(?:\s+$stuff?)?$" test fails
 110      There must be n test lines where n (possibly 0) is from the test plan.
 111      If present, $stuff should match
 112         "(\d+)?\s*([^#]*)(?:#\s*(?i)(SKIP|TODO)\b(.*))?"
 113      where $1 is the test number and if present must be correct (tests are
 114      numbered starting with 1).  $2 is the optional test description and it's
 115      customary to start it with "- " to make the output look nice.  If present,
 116      $3 is a directive and $4 is the reason for it.  An "ok #TODO" is a known
 117      breakage that isn't actually broken.  A "not ok #TODO" is a known breakage
 118      (that's still broken).  An "ok #SKIP" is a skipped test.  A "not ok #SKIP"
 119      is treated the same as a "not ok" test.  For example, the following shows
 120      four test lines for good, skip, bad and known broken respectively:
 121          ok 1 - test that works
 122          ok 2 - test might work # SKIP need missing thingamajig to run
 123          not ok 3 - test that should have worked
 124          not ok 4 - test known not to work # TODO fix this problem
 125
 126   3) Diagnostic/Comment lines matching "^#" which are ignored for TAP purposes
 127      (If the '#' isn't in column 1 then it's technically an "other" line.)
 128      Some harnesses have an option to show comments and "other" lines do NOT
 129      qualify, only lines matching "^#" are considered "comments".  For example,
 130      all of the following are recognized as comment/diagnostice lines:
 131          # Hello
 132          #   some random gobbledygook
 133          # Lines may be located anywhere in the output
 134
 135   4) An emergency stop line matching "^\s*Bail out!\s*(.*)$" (yes, it IS
 136      case-sensitive).  The value of $1 will be shown if present.
 137      (A well-written test emits a '1..0 # SKIP ...' line instead, but if
 138      something unrecoverable goes wrong in the middle of testing a "Bail out!"
 139      line is useful.)  For example:
 140          Bail out! my microphone is broken
 141      When using prove to run multiple tests a 'Bail out!' line will abort all
 142      further testing when it's encountered (including any yet-to-be-run tests).
 143
 144 The handling of other lines is unspecified although generally they are treated
 145 as lines to be ignored, but should the TAP standard change there is no
 146 guarantee they will continue to be so treated.