t/README

   1 Test Files
   2 ==========
   3
   4 All tests are shell scripts and must be named to
   5 match (shell glob):
   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 <https://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 is no requirement that
  71     the description follow any particular layout.  It is
  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 (perl regular expressions) either:
  99
 100        a) `^1\.\.$count$` where `$count` is a positive integer
 101        b) `^1\.\.0(?![0-9]).*?#\s*(?i)SKIP\S*\s+(.*)$` where $1 is skip reason
 102           (this format is only valid if there are no test lines)
 103
 104     There MUST BE EXACTLY ONE test plan line and it must appear either
 105     BEFORE ALL or AFTER ALL of the test lines.  For example, the following
 106     line plans four tests:
 107
 108         1..4
 109
 110  2) Test lines which must either be ALL BEFORE or ALL AFTER the test plan line:
 111
 112        a) `^ok(?:\s+$stuff?)?$` test succeeds
 113        b) `^not ok(?:\s+$stuff?)?$` test fails
 114
 115     There must be n test lines where n (possibly 0) is from the test plan.
 116     If present, `$stuff` should match:
 117
 118         (\d+)?\s*([^#]*)(?:#\s*(?i)(SKIP|TODO)\b(.*))?
 119
 120     where $1 is the test number and if present must be correct (tests are
 121     numbered starting with 1).  $2 is the optional test description and it's
 122     customary to start it with "- " to make the output look nice.  If present,
 123     $3 is a directive and $4 is the reason for it.  An "ok #TODO" is a known
 124     breakage that isn't actually broken.  A "not ok #TODO" is a known breakage
 125     (that's still broken).  An "ok #SKIP" is a skipped test.  A "not ok #SKIP"
 126     is treated the same as a "not ok" test.  For example, the following shows
 127     four test lines for good, skip, bad and known broken respectively:
 128
 129         ok 1 - test that works
 130         ok 2 - test might work # SKIP need missing thingamajig to run
 131         not ok 3 - test that should have worked
 132         not ok 4 - test known not to work # TODO fix this problem
 133
 134  3) Diagnostic/Comment lines matching `^#` which are ignored for TAP purposes
 135     (If the `'#'` isn't in column 1 then it's technically an "other" line.)
 136     Some harnesses have an option to show comments and "other" lines do NOT
 137     qualify, only lines matching `^#` are considered "comments".  For example,
 138     all of the following are recognized as comment/diagnostic lines:
 139
 140         # Hello
 141         #   some random gobbledygook
 142         # Lines may be located anywhere in the output
 143
 144  4) An emergency stop line matching `^\s*Bail out!\s*(.*)$` (yes, it IS
 145     case-sensitive).  The value of $1 will be shown if present.
 146     (A well-written test emits a '1..0 # SKIP ...' line instead, but if
 147     something unrecoverable goes wrong in the middle of testing a "Bail out!"
 148     line is useful.)  For example:
 149
 150         Bail out! my microphone is broken
 151
 152     When using prove to run multiple tests a `'Bail out!'` line will abort all
 153     further testing when it's encountered (including any yet-to-be-run tests).
 154
 155 The handling of other lines is unspecified although generally they are treated
 156 as lines to be ignored, but should the TAP standard change there is no
 157 guarantee they will continue to be so treated.