]>
Commit | Line | Data |
---|---|---|
986aa7f1 JH |
1 | Core GIT Tests |
2 | ============== | |
3 | ||
4 | This directory holds many test scripts for core GIT tools. The | |
5 | first part of this short document describes how to run the tests | |
6 | and read their output. | |
7 | ||
8 | When fixing the tools or adding enhancements, you are strongly | |
9 | encouraged to add tests in this directory to cover what you are | |
10 | trying to fix or enhance. The later part of this short document | |
11 | describes how your test scripts should be organized. | |
12 | ||
13 | ||
14 | Running Tests | |
15 | ------------- | |
16 | ||
17 | The easiest way to run tests is to say "make". This runs all | |
18 | the tests. | |
19 | ||
20 | *** t0000-basic.sh *** | |
5099b99d ÆAB |
21 | ok 1 - .git/objects should be empty after git init in an empty repo. |
22 | ok 2 - .git/objects should have 3 subdirectories. | |
23 | ok 3 - success is reported like this | |
986aa7f1 | 24 | ... |
5099b99d ÆAB |
25 | ok 43 - very long name in the index handled sanely |
26 | # fixed 1 known breakage(s) | |
27 | # still have 1 known breakage(s) | |
28 | # passed all remaining 42 test(s) | |
29 | 1..43 | |
30 | *** t0001-init.sh *** | |
31 | ok 1 - plain | |
32 | ok 2 - plain with GIT_WORK_TREE | |
33 | ok 3 - plain bare | |
34 | ||
35 | Since the tests all output TAP (see http://testanything.org) they can | |
85b0b34e | 36 | be run with any TAP harness. Here's an example of parallel testing |
5099b99d ÆAB |
37 | powered by a recent version of prove(1): |
38 | ||
39 | $ prove --timer --jobs 15 ./t[0-9]*.sh | |
40 | [19:17:33] ./t0005-signals.sh ................................... ok 36 ms | |
41 | [19:17:33] ./t0022-crlf-rename.sh ............................... ok 69 ms | |
42 | [19:17:33] ./t0024-crlf-archive.sh .............................. ok 154 ms | |
43 | [19:17:33] ./t0004-unwritable.sh ................................ ok 289 ms | |
44 | [19:17:33] ./t0002-gitfile.sh ................................... ok 480 ms | |
45 | ===( 102;0 25/? 6/? 5/? 16/? 1/? 4/? 2/? 1/? 3/? 1... )=== | |
46 | ||
47 | prove and other harnesses come with a lot of useful options. The | |
48 | --state option in particular is very useful: | |
49 | ||
50 | # Repeat until no more failures | |
51 | $ prove -j 15 --state=failed,save ./t[0-9]*.sh | |
986aa7f1 | 52 | |
28d836c8 MG |
53 | You can give DEFAULT_TEST_TARGET=prove on the make command (or define it |
54 | in config.mak) to cause "make test" to run tests under prove. | |
55 | GIT_PROVE_OPTS can be used to pass additional options, e.g. | |
56 | ||
57 | $ make DEFAULT_TEST_TARGET=prove GIT_PROVE_OPTS='--timer --jobs 16' test | |
58 | ||
5099b99d | 59 | You can also run each test individually from command line, like this: |
986aa7f1 | 60 | |
5099b99d ÆAB |
61 | $ sh ./t3010-ls-files-killed-modified.sh |
62 | ok 1 - git update-index --add to add various paths. | |
63 | ok 2 - git ls-files -k to show killed files. | |
64 | ok 3 - validate git ls-files -k output. | |
65 | ok 4 - git ls-files -m to show modified files. | |
66 | ok 5 - validate git ls-files -m output. | |
67 | # passed all 5 test(s) | |
68 | 1..5 | |
986aa7f1 JH |
69 | |
70 | You can pass --verbose (or -v), --debug (or -d), and --immediate | |
4e1be63c JS |
71 | (or -i) command line argument to the test, or by setting GIT_TEST_OPTS |
72 | appropriately before running "make". | |
986aa7f1 | 73 | |
5e3b4fce | 74 | -v:: |
986aa7f1 JH |
75 | --verbose:: |
76 | This makes the test more verbose. Specifically, the | |
77 | command being run and their output if any are also | |
78 | output. | |
79 | ||
ff09af3f TR |
80 | --verbose-only=<pattern>:: |
81 | Like --verbose, but the effect is limited to tests with | |
82 | numbers matching <pattern>. The number matched against is | |
83 | simply the running count of the test within the file. | |
84 | ||
5e3b4fce | 85 | -d:: |
986aa7f1 JH |
86 | --debug:: |
87 | This may help the person who is developing a new test. | |
88 | It causes the command defined with test_debug to run. | |
0986de94 PK |
89 | The "trash" directory (used to store all temporary data |
90 | during testing) is not deleted even if there are no | |
91 | failed tests so that you can inspect its contents after | |
92 | the test finished. | |
986aa7f1 | 93 | |
5e3b4fce | 94 | -i:: |
986aa7f1 JH |
95 | --immediate:: |
96 | This causes the test to immediately exit upon the first | |
13cb3bb7 SR |
97 | failed test. Cleanup commands requested with |
98 | test_when_finished are not executed if the test failed, | |
99 | in order to keep the state for inspection by the tester | |
100 | to diagnose the bug. | |
986aa7f1 | 101 | |
5e3b4fce | 102 | -l:: |
5e2c08c6 LW |
103 | --long-tests:: |
104 | This causes additional long-running tests to be run (where | |
105 | available), for more exhaustive testing. | |
106 | ||
0445e6f0 IB |
107 | -r:: |
108 | --run=<test-selector>:: | |
109 | Run only the subset of tests indicated by | |
110 | <test-selector>. See section "Skipping Tests" below for | |
111 | <test-selector> syntax. | |
112 | ||
952af351 TR |
113 | --valgrind=<tool>:: |
114 | Execute all Git binaries under valgrind tool <tool> and exit | |
115 | with status 126 on errors (just like regular tests, this will | |
116 | only stop the test script when running under -i). | |
986aa7f1 | 117 | |
3da93652 JS |
118 | Since it makes no sense to run the tests with --valgrind and |
119 | not see any output, this option implies --verbose. For | |
120 | convenience, it also implies --tee. | |
121 | ||
952af351 TR |
122 | <tool> defaults to 'memcheck', just like valgrind itself. |
123 | Other particularly useful choices include 'helgrind' and | |
124 | 'drd', but you may use any tool recognized by your valgrind | |
125 | installation. | |
126 | ||
95d9d5ec TR |
127 | As a special case, <tool> can be 'memcheck-fast', which uses |
128 | memcheck but disables --track-origins. Use this if you are | |
129 | running tests in bulk, to see if there are _any_ memory | |
130 | issues. | |
131 | ||
952af351 | 132 | Note that memcheck is run with the option --leak-check=no, |
9aec68d3 CMN |
133 | as the git process is short-lived and some errors are not |
134 | interesting. In order to run a single command under the same | |
135 | conditions manually, you should set GIT_VALGRIND to point to | |
136 | the 't/valgrind/' directory and use the commands under | |
137 | 't/valgrind/bin/'. | |
138 | ||
5dfc368f TR |
139 | --valgrind-only=<pattern>:: |
140 | Like --valgrind, but the effect is limited to tests with | |
141 | numbers matching <pattern>. The number matched against is | |
142 | simply the running count of the test within the file. | |
143 | ||
44138559 JS |
144 | --tee:: |
145 | In addition to printing the test output to the terminal, | |
146 | write it to files named 't/test-results/$TEST_NAME.out'. | |
147 | As the names depend on the tests' file names, it is safe to | |
148 | run the tests with this option in parallel. | |
149 | ||
e4597aae MO |
150 | --with-dashes:: |
151 | By default tests are run without dashed forms of | |
152 | commands (like git-commit) in the PATH (it only uses | |
153 | wrappers from ../bin-wrappers). Use this option to include | |
154 | the build directory (..) in the PATH, which contains all | |
155 | the dashed forms of commands. This option is currently | |
156 | implied by other options like --valgrind and | |
157 | GIT_TEST_INSTALLED. | |
158 | ||
0d4dbcd3 TR |
159 | --root=<directory>:: |
160 | Create "trash" directories used to store all temporary data during | |
161 | testing under <directory>, instead of the t/ directory. | |
162 | Using this option with a RAM-based filesystem (such as tmpfs) | |
163 | can massively speed up the test suite. | |
164 | ||
e160da7f MO |
165 | You can also set the GIT_TEST_INSTALLED environment variable to |
166 | the bindir of an existing git installation to test that installation. | |
167 | You still need to have built this git sandbox, from which various | |
168 | test-* support programs, templates, and perl libraries are used. | |
169 | If your installed git is incomplete, it will silently test parts of | |
170 | your built version instead. | |
171 | ||
172 | When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to | |
173 | override the location of the dashed-form subcommands (what | |
174 | GIT_EXEC_PATH would be used for during normal operation). | |
175 | GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`. | |
176 | ||
177 | ||
fbd458a3 JN |
178 | Skipping Tests |
179 | -------------- | |
180 | ||
181 | In some environments, certain tests have no way of succeeding | |
182 | due to platform limitation, such as lack of 'unzip' program, or | |
183 | filesystem that do not allow arbitrary sequence of non-NUL bytes | |
184 | as pathnames. | |
185 | ||
186 | You should be able to say something like | |
187 | ||
188 | $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh | |
189 | ||
190 | and even: | |
191 | ||
192 | $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make | |
193 | ||
194 | to omit such tests. The value of the environment variable is a | |
195 | SP separated list of patterns that tells which tests to skip, | |
196 | and either can match the "t[0-9]{4}" part to skip the whole | |
197 | test, or t[0-9]{4} followed by ".$number" to say which | |
198 | particular test to skip. | |
199 | ||
0445e6f0 IB |
200 | For an individual test suite --run could be used to specify that |
201 | only some tests should be run or that some tests should be | |
202 | excluded from a run. | |
203 | ||
204 | The argument for --run is a list of individual test numbers or | |
205 | ranges with an optional negation prefix that define what tests in | |
206 | a test suite to include in the run. A range is two numbers | |
207 | separated with a dash and matches a range of tests with both ends | |
208 | been included. You may omit the first or the second number to | |
209 | mean "from the first test" or "up to the very last test" | |
210 | respectively. | |
211 | ||
212 | Optional prefix of '!' means that the test or a range of tests | |
213 | should be excluded from the run. | |
214 | ||
215 | If --run starts with an unprefixed number or range the initial | |
216 | set of tests to run is empty. If the first item starts with '!' | |
217 | all the tests are added to the initial set. After initial set is | |
218 | determined every test number or range is added or excluded from | |
219 | the set one by one, from left to right. | |
220 | ||
221 | Individual numbers or ranges could be separated either by a space | |
222 | or a comma. | |
223 | ||
224 | For example, to run only tests up to a specific test (21), one | |
225 | could do this: | |
226 | ||
227 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-21' | |
228 | ||
229 | or this: | |
230 | ||
231 | $ sh ./t9200-git-cvsexport-commit.sh --run='-21' | |
232 | ||
233 | Common case is to run several setup tests (1, 2, 3) and then a | |
234 | specific test (21) that relies on that setup: | |
235 | ||
236 | $ sh ./t9200-git-cvsexport-commit.sh --run='1 2 3 21' | |
237 | ||
238 | or: | |
239 | ||
240 | $ sh ./t9200-git-cvsexport-commit.sh --run=1,2,3,21 | |
241 | ||
242 | or: | |
243 | ||
244 | $ sh ./t9200-git-cvsexport-commit.sh --run='-3 21' | |
245 | ||
246 | As noted above, the test set is built going though items left to | |
247 | right, so this: | |
248 | ||
249 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-4 !3' | |
250 | ||
251 | will run tests 1, 2, and 4. Items that comes later have higher | |
252 | precendence. It means that this: | |
253 | ||
254 | $ sh ./t9200-git-cvsexport-commit.sh --run='!3 1-4' | |
255 | ||
256 | would just run tests from 1 to 4, including 3. | |
257 | ||
258 | You may use negation with ranges. The following will run all | |
259 | test in the test suite except from 7 up to 11: | |
260 | ||
261 | $ sh ./t9200-git-cvsexport-commit.sh --run='!7-11' | |
262 | ||
263 | Some tests in a test suite rely on the previous tests performing | |
264 | certain actions, specifically some tests are designated as | |
265 | "setup" test, so you cannot _arbitrarily_ disable one test and | |
266 | expect the rest to function correctly. | |
267 | ||
268 | --run is mostly useful when you want to focus on a specific test | |
269 | and know what setup is needed for it. Or when you want to run | |
270 | everything up to a certain test. | |
fbd458a3 JN |
271 | |
272 | ||
f50c9f76 PB |
273 | Naming Tests |
274 | ------------ | |
275 | ||
276 | The test files are named as: | |
277 | ||
278 | tNNNN-commandname-details.sh | |
279 | ||
280 | where N is a decimal digit. | |
281 | ||
282 | First digit tells the family: | |
283 | ||
284 | 0 - the absolute basics and global stuff | |
285 | 1 - the basic commands concerning database | |
286 | 2 - the basic commands concerning the working tree | |
287 | 3 - the other basic commands (e.g. ls-files) | |
288 | 4 - the diff commands | |
289 | 5 - the pull and exporting commands | |
290 | 6 - the revision tree commands (even e.g. merge-base) | |
8f4a9b62 | 291 | 7 - the porcelainish commands concerning the working tree |
8757749e JN |
292 | 8 - the porcelainish commands concerning forensics |
293 | 9 - the git tools | |
f50c9f76 PB |
294 | |
295 | Second digit tells the particular command we are testing. | |
296 | ||
297 | Third digit (optionally) tells the particular switch or group of switches | |
298 | we are testing. | |
299 | ||
77656600 JH |
300 | If you create files under t/ directory (i.e. here) that is not |
301 | the top-level test script, never name the file to match the above | |
302 | pattern. The Makefile here considers all such files as the | |
63d32945 | 303 | top-level test script and tries to run all of them. Care is |
77656600 JH |
304 | especially needed if you are creating a common test library |
305 | file, similar to test-lib.sh, because such a library file may | |
306 | not be suitable for standalone execution. | |
307 | ||
f50c9f76 | 308 | |
986aa7f1 JH |
309 | Writing Tests |
310 | ------------- | |
311 | ||
312 | The test script is written as a shell script. It should start | |
313 | with the standard "#!/bin/sh" with copyright notices, and an | |
314 | assignment to variable 'test_description', like this: | |
315 | ||
316 | #!/bin/sh | |
317 | # | |
318 | # Copyright (c) 2005 Junio C Hamano | |
319 | # | |
320 | ||
14cd1ff3 | 321 | test_description='xxx test (option --frotz) |
986aa7f1 JH |
322 | |
323 | This test registers the following structure in the cache | |
324 | and tries to run git-ls-files with option --frotz.' | |
325 | ||
f50c9f76 | 326 | |
986aa7f1 JH |
327 | Source 'test-lib.sh' |
328 | -------------------- | |
329 | ||
330 | After assigning test_description, the test script should source | |
331 | test-lib.sh like this: | |
332 | ||
333 | . ./test-lib.sh | |
334 | ||
335 | This test harness library does the following things: | |
336 | ||
337 | - If the script is invoked with command line argument --help | |
338 | (or -h), it shows the test_description and exits. | |
339 | ||
e1ca1c9d ÆAB |
340 | - Creates an empty test directory with an empty .git/objects database |
341 | and chdir(2) into it. This directory is 't/trash | |
342 | directory.$test_name_without_dotsh', with t/ subject to change by | |
343 | the --root option documented above. | |
986aa7f1 JH |
344 | |
345 | - Defines standard test helper functions for your scripts to | |
346 | use. These functions are designed to make all scripts behave | |
347 | consistently when command line arguments --verbose (or -v), | |
348 | --debug (or -d), and --immediate (or -i) is given. | |
349 | ||
20873f45 ÆAB |
350 | Do's, don'ts & things to keep in mind |
351 | ------------------------------------- | |
352 | ||
6fd45295 | 353 | Here are a few examples of things you probably should and shouldn't do |
20873f45 ÆAB |
354 | when writing tests. |
355 | ||
356 | Do: | |
357 | ||
6fd45295 | 358 | - Put all code inside test_expect_success and other assertions. |
20873f45 ÆAB |
359 | |
360 | Even code that isn't a test per se, but merely some setup code | |
6fd45295 | 361 | should be inside a test assertion. |
20873f45 ÆAB |
362 | |
363 | - Chain your test assertions | |
364 | ||
365 | Write test code like this: | |
366 | ||
367 | git merge foo && | |
368 | git push bar && | |
369 | test ... | |
370 | ||
371 | Instead of: | |
372 | ||
373 | git merge hla | |
374 | git push gh | |
375 | test ... | |
376 | ||
377 | That way all of the commands in your tests will succeed or fail. If | |
00648ba0 EN |
378 | you must ignore the return value of something, consider using a |
379 | helper function (e.g. use sane_unset instead of unset, in order | |
380 | to avoid unportable return value for unsetting a variable that was | |
381 | already unset), or prepending the command with test_might_fail or | |
382 | test_must_fail. | |
20873f45 | 383 | |
0c357544 ÆAB |
384 | - Check the test coverage for your tests. See the "Test coverage" |
385 | below. | |
386 | ||
63d32945 MW |
387 | Don't blindly follow test coverage metrics; if a new function you added |
388 | doesn't have any coverage, then you're probably doing something wrong, | |
e8b55f5c ÆAB |
389 | but having 100% coverage doesn't necessarily mean that you tested |
390 | everything. | |
391 | ||
392 | Tests that are likely to smoke out future regressions are better | |
393 | than tests that just inflate the coverage metrics. | |
394 | ||
95b104c8 JS |
395 | - When a test checks for an absolute path that a git command generated, |
396 | construct the expected value using $(pwd) rather than $PWD, | |
397 | $TEST_DIRECTORY, or $TRASH_DIRECTORY. It makes a difference on | |
398 | Windows, where the shell (MSYS bash) mangles absolute path names. | |
399 | For details, see the commit message of 4114156ae9. | |
400 | ||
20873f45 ÆAB |
401 | Don't: |
402 | ||
403 | - exit() within a <script> part. | |
404 | ||
405 | The harness will catch this as a programming error of the test. | |
406 | Use test_done instead if you need to stop the tests early (see | |
407 | "Skipping tests" below). | |
408 | ||
ad78585e JH |
409 | - use '! git cmd' when you want to make sure the git command exits |
410 | with failure in a controlled way by calling "die()". Instead, | |
411 | use 'test_must_fail git cmd'. This will signal a failure if git | |
412 | dies in an unexpected way (e.g. segfault). | |
413 | ||
f445500e JH |
414 | On the other hand, don't use test_must_fail for running regular |
415 | platform commands; just use '! cmd'. | |
416 | ||
ad78585e JH |
417 | - use perl without spelling it as "$PERL_PATH". This is to help our |
418 | friends on Windows where the platform Perl often adds CR before | |
419 | the end of line, and they bundle Git with a version of Perl that | |
a0e0ec9f JK |
420 | does not do so, whose path is specified with $PERL_PATH. Note that we |
421 | provide a "perl" function which uses $PERL_PATH under the hood, so | |
422 | you do not need to worry when simply running perl in the test scripts | |
423 | (but you do, for example, on a shebang line or in a sub script | |
424 | created via "write_script"). | |
ad78585e JH |
425 | |
426 | - use sh without spelling it as "$SHELL_PATH", when the script can | |
427 | be misinterpreted by broken platform shell (e.g. Solaris). | |
428 | ||
429 | - chdir around in tests. It is not sufficient to chdir to | |
430 | somewhere and then chdir back to the original location later in | |
431 | the test, as any intermediate step can fail and abort the test, | |
432 | causing the next test to start in an unexpected directory. Do so | |
433 | inside a subshell if necessary. | |
434 | ||
20873f45 ÆAB |
435 | - Break the TAP output |
436 | ||
6fd45295 JH |
437 | The raw output from your test may be interpreted by a TAP harness. TAP |
438 | harnesses will ignore everything they don't know about, but don't step | |
439 | on their toes in these areas: | |
20873f45 ÆAB |
440 | |
441 | - Don't print lines like "$x..$y" where $x and $y are integers. | |
442 | ||
443 | - Don't print lines that begin with "ok" or "not ok". | |
444 | ||
6fd45295 | 445 | TAP harnesses expect a line that begins with either "ok" and "not |
20873f45 ÆAB |
446 | ok" to signal a test passed or failed (and our harness already |
447 | produces such lines), so your script shouldn't emit such lines to | |
448 | their output. | |
449 | ||
450 | You can glean some further possible issues from the TAP grammar | |
451 | (see http://search.cpan.org/perldoc?TAP::Parser::Grammar#TAP_Grammar) | |
452 | but the best indication is to just run the tests with prove(1), | |
453 | it'll complain if anything is amiss. | |
454 | ||
455 | Keep in mind: | |
456 | ||
6fd45295 | 457 | - Inside <script> part, the standard output and standard error |
20873f45 ÆAB |
458 | streams are discarded, and the test harness only reports "ok" or |
459 | "not ok" to the end user running the tests. Under --verbose, they | |
460 | are shown to help debugging the tests. | |
461 | ||
462 | ||
b5500d16 ÆAB |
463 | Skipping tests |
464 | -------------- | |
465 | ||
681186ae | 466 | If you need to skip tests you should do so by using the three-arg form |
99d9050d ÆAB |
467 | of the test_* functions (see the "Test harness library" section |
468 | below), e.g.: | |
469 | ||
ad78585e | 470 | test_expect_success PERL 'I need Perl' ' |
a0e0ec9f | 471 | perl -e "hlagh() if unf_unf()" |
ad78585e | 472 | ' |
99d9050d ÆAB |
473 | |
474 | The advantage of skipping tests like this is that platforms that don't | |
475 | have the PERL and other optional dependencies get an indication of how | |
476 | many tests they're missing. | |
477 | ||
478 | If the test code is too hairy for that (i.e. does a lot of setup work | |
479 | outside test assertions) you can also skip all remaining tests by | |
480 | setting skip_all and immediately call test_done: | |
b5500d16 ÆAB |
481 | |
482 | if ! test_have_prereq PERL | |
483 | then | |
484 | skip_all='skipping perl interface tests, perl not available' | |
485 | test_done | |
486 | fi | |
14cd1ff3 | 487 | |
99d9050d ÆAB |
488 | The string you give to skip_all will be used as an explanation for why |
489 | the test was skipped. | |
490 | ||
986aa7f1 JH |
491 | End with test_done |
492 | ------------------ | |
493 | ||
494 | Your script will be a sequence of tests, using helper functions | |
495 | from the test harness library. At the end of the script, call | |
496 | 'test_done'. | |
497 | ||
498 | ||
499 | Test harness library | |
500 | -------------------- | |
501 | ||
502 | There are a handful helper functions defined in the test harness | |
503 | library for your script to use. | |
504 | ||
9a897893 | 505 | - test_expect_success [<prereq>] <message> <script> |
986aa7f1 | 506 | |
72942a61 | 507 | Usually takes two strings as parameters, and evaluates the |
986aa7f1 JH |
508 | <script>. If it yields success, test is considered |
509 | successful. <message> should state what it is testing. | |
510 | ||
511 | Example: | |
512 | ||
513 | test_expect_success \ | |
514 | 'git-write-tree should be able to write an empty tree.' \ | |
515 | 'tree=$(git-write-tree)' | |
516 | ||
9a897893 | 517 | If you supply three parameters the first will be taken to be a |
72942a61 | 518 | prerequisite; see the test_set_prereq and test_have_prereq |
9a897893 ÆAB |
519 | documentation below: |
520 | ||
521 | test_expect_success TTY 'git --paginate rev-list uses a pager' \ | |
522 | ' ... ' | |
523 | ||
93a57246 ÆAB |
524 | You can also supply a comma-separated list of prerequisites, in the |
525 | rare case where your test depends on more than one: | |
526 | ||
527 | test_expect_success PERL,PYTHON 'yo dawg' \ | |
528 | ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" ' | |
529 | ||
9a897893 | 530 | - test_expect_failure [<prereq>] <message> <script> |
986aa7f1 | 531 | |
41ac414e JH |
532 | This is NOT the opposite of test_expect_success, but is used |
533 | to mark a test that demonstrates a known breakage. Unlike | |
534 | the usual test_expect_success tests, which say "ok" on | |
535 | success and "FAIL" on failure, this will say "FIXED" on | |
536 | success and "still broken" on failure. Failures from these | |
537 | tests won't cause -i (immediate) to stop. | |
986aa7f1 | 538 | |
9a897893 ÆAB |
539 | Like test_expect_success this function can optionally use a three |
540 | argument invocation with a prerequisite as the first argument. | |
541 | ||
986aa7f1 JH |
542 | - test_debug <script> |
543 | ||
544 | This takes a single argument, <script>, and evaluates it only | |
545 | when the test script is started with --debug command line | |
546 | argument. This is primarily meant for use during the | |
547 | development of a new test script. | |
548 | ||
549 | - test_done | |
550 | ||
551 | Your test script must have test_done at the end. Its purpose | |
552 | is to summarize successes and failures in the test script and | |
553 | exit with an appropriate error code. | |
554 | ||
00884968 JS |
555 | - test_tick |
556 | ||
557 | Make commit and tag names consistent by setting the author and | |
63d32945 | 558 | committer times to defined state. Subsequent calls will |
00884968 JS |
559 | advance the times by a fixed amount. |
560 | ||
561 | - test_commit <message> [<filename> [<contents>]] | |
562 | ||
563 | Creates a commit with the given message, committing the given | |
564 | file with the given contents (default for both is to reuse the | |
565 | message string), and adds a tag (again reusing the message | |
566 | string as name). Calls test_tick to make the SHA-1s | |
567 | reproducible. | |
568 | ||
569 | - test_merge <message> <commit-or-tag> | |
570 | ||
571 | Merges the given rev using the given message. Like test_commit, | |
572 | creates a tag and calls test_tick before committing. | |
986aa7f1 | 573 | |
72942a61 | 574 | - test_set_prereq <prereq> |
9a897893 ÆAB |
575 | |
576 | Set a test prerequisite to be used later with test_have_prereq. The | |
be53deef ÆAB |
577 | test-lib will set some prerequisites for you, see the |
578 | "Prerequisites" section below for a full list of these. | |
579 | ||
580 | Others you can set yourself and use later with either | |
581 | test_have_prereq directly, or the three argument invocation of | |
582 | test_expect_success and test_expect_failure. | |
9a897893 | 583 | |
72942a61 | 584 | - test_have_prereq <prereq> |
9a897893 ÆAB |
585 | |
586 | Check if we have a prerequisite previously set with | |
587 | test_set_prereq. The most common use of this directly is to skip | |
588 | all the tests if we don't have some essential prerequisite: | |
589 | ||
590 | if ! test_have_prereq PERL | |
591 | then | |
592 | skip_all='skipping perl interface tests, perl not available' | |
593 | test_done | |
594 | fi | |
595 | ||
2fac6a4b ÆAB |
596 | - test_external [<prereq>] <message> <external> <script> |
597 | ||
598 | Execute a <script> with an <external> interpreter (like perl). This | |
599 | was added for tests like t9700-perl-git.sh which do most of their | |
600 | work in an external test script. | |
601 | ||
602 | test_external \ | |
603 | 'GitwebCache::*FileCache*' \ | |
a0e0ec9f | 604 | perl "$TEST_DIRECTORY"/t9503/test_cache_interface.pl |
2fac6a4b ÆAB |
605 | |
606 | If the test is outputting its own TAP you should set the | |
607 | test_external_has_tap variable somewhere before calling the first | |
608 | test_external* function. See t9700-perl-git.sh for an example. | |
609 | ||
610 | # The external test will outputs its own plan | |
611 | test_external_has_tap=1 | |
612 | ||
613 | - test_external_without_stderr [<prereq>] <message> <external> <script> | |
614 | ||
615 | Like test_external but fail if there's any output on stderr, | |
616 | instead of checking the exit code. | |
617 | ||
618 | test_external_without_stderr \ | |
619 | 'Perl API' \ | |
a0e0ec9f | 620 | perl "$TEST_DIRECTORY"/t9700/test.pl |
2fac6a4b | 621 | |
892e6f7e ÆAB |
622 | - test_expect_code <exit-code> <command> |
623 | ||
624 | Run a command and ensure that it exits with the given exit code. | |
625 | For example: | |
626 | ||
627 | test_expect_success 'Merge with d/f conflicts' ' | |
628 | test_expect_code 1 git merge "merge msg" B master | |
629 | ' | |
630 | ||
c9667456 JN |
631 | - test_must_fail <git-command> |
632 | ||
633 | Run a git command and ensure it fails in a controlled way. Use | |
971ecbd1 BC |
634 | this instead of "! <git-command>". When git-command dies due to a |
635 | segfault, test_must_fail diagnoses it as an error; "! <git-command>" | |
636 | treats it as just another expected failure, which would let such a | |
637 | bug go unnoticed. | |
c9667456 JN |
638 | |
639 | - test_might_fail <git-command> | |
640 | ||
641 | Similar to test_must_fail, but tolerate success, too. Use this | |
642 | instead of "<git-command> || :" to catch failures due to segv. | |
643 | ||
644 | - test_cmp <expected> <actual> | |
645 | ||
646 | Check whether the content of the <actual> file matches the | |
647 | <expected> file. This behaves like "cmp" but produces more | |
648 | helpful output when the test is run with "-v" option. | |
649 | ||
fb3340a6 JN |
650 | - test_line_count (= | -lt | -ge | ...) <length> <file> |
651 | ||
652 | Check whether a file has the length it is expected to. | |
653 | ||
72942a61 ML |
654 | - test_path_is_file <path> [<diagnosis>] |
655 | test_path_is_dir <path> [<diagnosis>] | |
2caf20c5 MM |
656 | test_path_is_missing <path> [<diagnosis>] |
657 | ||
72942a61 ML |
658 | Check if the named path is a file, if the named path is a |
659 | directory, or if the named path does not exist, respectively, | |
660 | and fail otherwise, showing the <diagnosis> text. | |
2caf20c5 | 661 | |
c9667456 JN |
662 | - test_when_finished <script> |
663 | ||
664 | Prepend <script> to a list of commands to run to clean up | |
665 | at the end of the current test. If some clean-up command | |
666 | fails, the test will not pass. | |
667 | ||
668 | Example: | |
669 | ||
670 | test_expect_success 'branch pointing to non-commit' ' | |
671 | git rev-parse HEAD^{tree} >.git/refs/heads/invalid && | |
672 | test_when_finished "git update-ref -d refs/heads/invalid" && | |
673 | ... | |
674 | ' | |
675 | ||
bb98b01e | 676 | - test_write_lines <lines> |
ac9afcc3 | 677 | |
bb98b01e | 678 | Write <lines> on standard output, one line per argument. |
ac9afcc3 MT |
679 | Useful to prepare multi-line files in a compact form. |
680 | ||
681 | Example: | |
682 | ||
bb98b01e | 683 | test_write_lines a b c d e f g >foo |
ac9afcc3 MT |
684 | |
685 | Is a more compact equivalent of: | |
686 | cat >foo <<-EOF | |
687 | a | |
688 | b | |
689 | c | |
690 | d | |
691 | e | |
692 | f | |
693 | g | |
694 | EOF | |
695 | ||
696 | ||
c4d2539a JL |
697 | - test_pause |
698 | ||
699 | This command is useful for writing and debugging tests and must be | |
700 | removed before submitting. It halts the execution of the test and | |
701 | spawns a shell in the trash directory. Exit the shell to continue | |
702 | the test. Example: | |
703 | ||
704 | test_expect_success 'test' ' | |
705 | git do-something >actual && | |
706 | test_pause && | |
707 | test_cmp expected actual | |
708 | ' | |
709 | ||
9ce415d9 JS |
710 | - test_ln_s_add <path1> <path2> |
711 | ||
712 | This function helps systems whose filesystem does not support symbolic | |
713 | links. Use it to add a symbolic link entry to the index when it is not | |
714 | important that the file system entry is a symbolic link, i.e., instead | |
715 | of the sequence | |
716 | ||
717 | ln -s foo bar && | |
718 | git add bar | |
719 | ||
720 | Sometimes it is possible to split a test in a part that does not need | |
721 | the symbolic link in the file system and a part that does; then only | |
722 | the latter part need be protected by a SYMLINKS prerequisite (see below). | |
723 | ||
be53deef ÆAB |
724 | Prerequisites |
725 | ------------- | |
726 | ||
727 | These are the prerequisites that the test library predefines with | |
728 | test_have_prereq. | |
729 | ||
730 | See the prereq argument to the test_* functions in the "Test harness | |
731 | library" section above and the "test_have_prereq" function for how to | |
732 | use these, and "test_set_prereq" for how to define your own. | |
733 | ||
f8fc0ee3 | 734 | - PYTHON |
be53deef | 735 | |
f8fc0ee3 JN |
736 | Git wasn't compiled with NO_PYTHON=YesPlease. Wrap any tests that |
737 | need Python with this. | |
738 | ||
739 | - PERL | |
740 | ||
741 | Git wasn't compiled with NO_PERL=YesPlease. | |
742 | ||
743 | Even without the PERL prerequisite, tests can assume there is a | |
744 | usable perl interpreter at $PERL_PATH, though it need not be | |
745 | particularly modern. | |
be53deef ÆAB |
746 | |
747 | - POSIXPERM | |
748 | ||
749 | The filesystem supports POSIX style permission bits. | |
750 | ||
751 | - BSLASHPSPEC | |
752 | ||
753 | Backslashes in pathspec are not directory separators. This is not | |
754 | set on Windows. See 6fd1106a for details. | |
755 | ||
756 | - EXECKEEPSPID | |
757 | ||
758 | The process retains the same pid across exec(2). See fb9a2bea for | |
759 | details. | |
760 | ||
20073274 AS |
761 | - PIPE |
762 | ||
763 | The filesystem we're on supports creation of FIFOs (named pipes) | |
764 | via mkfifo(1). | |
765 | ||
be53deef ÆAB |
766 | - SYMLINKS |
767 | ||
768 | The filesystem we're on supports symbolic links. E.g. a FAT | |
769 | filesystem doesn't support these. See 704a3143 for details. | |
2fac6a4b | 770 | |
c91cfd19 ÆAB |
771 | - SANITY |
772 | ||
773 | Test is not run by root user, and an attempt to write to an | |
774 | unwritable file is expected to fail correctly. | |
2fac6a4b | 775 | |
8f852ce6 MK |
776 | - LIBPCRE |
777 | ||
778 | Git was compiled with USE_LIBPCRE=YesPlease. Wrap any tests | |
779 | that use git-grep --perl-regexp or git-grep -P in these. | |
780 | ||
ac39aa61 MG |
781 | - CASE_INSENSITIVE_FS |
782 | ||
783 | Test is run on a case insensitive file system. | |
784 | ||
5b0b5dd4 MG |
785 | - UTF8_NFD_TO_NFC |
786 | ||
787 | Test is run on a filesystem which converts decomposed utf-8 (nfd) | |
788 | to precomposed utf-8 (nfc). | |
789 | ||
986aa7f1 JH |
790 | Tips for Writing Tests |
791 | ---------------------- | |
792 | ||
793 | As with any programming projects, existing programs are the best | |
794 | source of the information. However, do _not_ emulate | |
795 | t0000-basic.sh when writing your tests. The test is special in | |
796 | that it tries to validate the very core of GIT. For example, it | |
797 | knows that there will be 256 subdirectories under .git/objects/, | |
798 | and it knows that the object ID of an empty tree is a certain | |
799 | 40-byte string. This is deliberately done so in t0000-basic.sh | |
800 | because the things the very basic core test tries to achieve is | |
801 | to serve as a basis for people who are changing the GIT internal | |
802 | drastically. For these people, after making certain changes, | |
803 | not seeing failures from the basic test _is_ a failure. And | |
804 | such drastic changes to the core GIT that even changes these | |
805 | otherwise supposedly stable object IDs should be accompanied by | |
806 | an update to t0000-basic.sh. | |
807 | ||
808 | However, other tests that simply rely on basic parts of the core | |
809 | GIT working properly should not have that level of intimate | |
810 | knowledge of the core GIT internals. If all the test scripts | |
811 | hardcoded the object IDs like t0000-basic.sh does, that defeats | |
812 | the purpose of t0000-basic.sh, which is to isolate that level of | |
813 | validation in one place. Your test also ends up needing | |
814 | updating when such a change to the internal happens, so do _not_ | |
815 | do it and leave the low level of validation to t0000-basic.sh. | |
d15e9ebc | 816 | |
0c357544 ÆAB |
817 | Test coverage |
818 | ------------- | |
819 | ||
820 | You can use the coverage tests to find code paths that are not being | |
821 | used or properly exercised yet. | |
822 | ||
823 | To do that, run the coverage target at the top-level (not in the t/ | |
824 | directory): | |
825 | ||
826 | make coverage | |
827 | ||
828 | That'll compile Git with GCC's coverage arguments, and generate a test | |
829 | report with gcov after the tests finish. Running the coverage tests | |
830 | can take a while, since running the tests in parallel is incompatible | |
831 | with GCC's coverage mode. | |
832 | ||
833 | After the tests have run you can generate a list of untested | |
834 | functions: | |
835 | ||
836 | make coverage-untested-functions | |
837 | ||
838 | You can also generate a detailed per-file HTML report using the | |
839 | Devel::Cover module. To install it do: | |
840 | ||
841 | # On Debian or Ubuntu: | |
842 | sudo aptitude install libdevel-cover-perl | |
843 | ||
844 | # From the CPAN with cpanminus | |
845 | curl -L http://cpanmin.us | perl - --sudo --self-upgrade | |
846 | cpanm --sudo Devel::Cover | |
847 | ||
848 | Then, at the top-level: | |
849 | ||
850 | make cover_db_html | |
851 | ||
852 | That'll generate a detailed cover report in the "cover_db_html" | |
853 | directory, which you can then copy to a webserver, or inspect locally | |
854 | in a browser. |