tg export: no need for merge or hook setup
[topgit/pro.git] / t / README
blob540e4eb099c96e30425fb6b2421d4dd8e84e87e7
1 Test Files
2 ==========
4 All tests are shell scripts and must be named to
5 match:
7     t[0-9][0-9][0-9][0-9]-*.sh
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.
17 All tests are run with the current directory set to the same
18 directory as the directory containing the test file itself.
21 -------------------------
22 Test Naming and Numbering
23 -------------------------
25 All the test scripts are named like so:
27     tNNNN-command-more-info.sh
29 Where `NNNN` is a 4-digit, 0-padded decimal number.
31 The first (i.e. leftmost) digit should indicate the category of the test as
32 follows:
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)
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.
49 Generally a given command should have all its tests in the same family.
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).
57 ------------
58 Test Library
59 ------------
61 A testing library is available to facilitate writing tests.
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:
67     test_description='title of test goes here
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     '
75     . ./test-lib.sh
77     test_expect_success 'small test' '
78         # do some testing
79         ...
80     '
82     ...
84     test_done
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.
91 ----------------------
92 TAP - A Quick Overview
93 ----------------------
95 Only output to STDOUT is examined and
96 must consist of one of four kinds of lines:
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
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
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
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).
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.