]>
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 | |
5099b99d | 53 | You can also run each test individually from command line, like this: |
986aa7f1 | 54 | |
5099b99d ÆAB |
55 | $ sh ./t3010-ls-files-killed-modified.sh |
56 | ok 1 - git update-index --add to add various paths. | |
57 | ok 2 - git ls-files -k to show killed files. | |
58 | ok 3 - validate git ls-files -k output. | |
59 | ok 4 - git ls-files -m to show modified files. | |
60 | ok 5 - validate git ls-files -m output. | |
61 | # passed all 5 test(s) | |
62 | 1..5 | |
986aa7f1 JH |
63 | |
64 | You can pass --verbose (or -v), --debug (or -d), and --immediate | |
4e1be63c JS |
65 | (or -i) command line argument to the test, or by setting GIT_TEST_OPTS |
66 | appropriately before running "make". | |
986aa7f1 JH |
67 | |
68 | --verbose:: | |
69 | This makes the test more verbose. Specifically, the | |
70 | command being run and their output if any are also | |
71 | output. | |
72 | ||
73 | --debug:: | |
74 | This may help the person who is developing a new test. | |
75 | It causes the command defined with test_debug to run. | |
76 | ||
77 | --immediate:: | |
78 | This causes the test to immediately exit upon the first | |
79 | failed test. | |
80 | ||
5e2c08c6 LW |
81 | --long-tests:: |
82 | This causes additional long-running tests to be run (where | |
83 | available), for more exhaustive testing. | |
84 | ||
4e1be63c JS |
85 | --valgrind:: |
86 | Execute all Git binaries with valgrind and exit with status | |
87 | 126 on errors (just like regular tests, this will only stop | |
88 | the test script when running under -i). Valgrind errors | |
89 | go to stderr, so you might want to pass the -v option, too. | |
986aa7f1 | 90 | |
3da93652 JS |
91 | Since it makes no sense to run the tests with --valgrind and |
92 | not see any output, this option implies --verbose. For | |
93 | convenience, it also implies --tee. | |
94 | ||
44138559 JS |
95 | --tee:: |
96 | In addition to printing the test output to the terminal, | |
97 | write it to files named 't/test-results/$TEST_NAME.out'. | |
98 | As the names depend on the tests' file names, it is safe to | |
99 | run the tests with this option in parallel. | |
100 | ||
e4597aae MO |
101 | --with-dashes:: |
102 | By default tests are run without dashed forms of | |
103 | commands (like git-commit) in the PATH (it only uses | |
104 | wrappers from ../bin-wrappers). Use this option to include | |
105 | the build directory (..) in the PATH, which contains all | |
106 | the dashed forms of commands. This option is currently | |
107 | implied by other options like --valgrind and | |
108 | GIT_TEST_INSTALLED. | |
109 | ||
0d4dbcd3 TR |
110 | --root=<directory>:: |
111 | Create "trash" directories used to store all temporary data during | |
112 | testing under <directory>, instead of the t/ directory. | |
113 | Using this option with a RAM-based filesystem (such as tmpfs) | |
114 | can massively speed up the test suite. | |
115 | ||
e160da7f MO |
116 | You can also set the GIT_TEST_INSTALLED environment variable to |
117 | the bindir of an existing git installation to test that installation. | |
118 | You still need to have built this git sandbox, from which various | |
119 | test-* support programs, templates, and perl libraries are used. | |
120 | If your installed git is incomplete, it will silently test parts of | |
121 | your built version instead. | |
122 | ||
123 | When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to | |
124 | override the location of the dashed-form subcommands (what | |
125 | GIT_EXEC_PATH would be used for during normal operation). | |
126 | GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`. | |
127 | ||
128 | ||
fbd458a3 JN |
129 | Skipping Tests |
130 | -------------- | |
131 | ||
132 | In some environments, certain tests have no way of succeeding | |
133 | due to platform limitation, such as lack of 'unzip' program, or | |
134 | filesystem that do not allow arbitrary sequence of non-NUL bytes | |
135 | as pathnames. | |
136 | ||
137 | You should be able to say something like | |
138 | ||
139 | $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh | |
140 | ||
141 | and even: | |
142 | ||
143 | $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make | |
144 | ||
145 | to omit such tests. The value of the environment variable is a | |
146 | SP separated list of patterns that tells which tests to skip, | |
147 | and either can match the "t[0-9]{4}" part to skip the whole | |
148 | test, or t[0-9]{4} followed by ".$number" to say which | |
149 | particular test to skip. | |
150 | ||
151 | Note that some tests in the existing test suite rely on previous | |
152 | test item, so you cannot arbitrarily disable one and expect the | |
153 | remainder of test to check what the test originally was intended | |
154 | to check. | |
155 | ||
156 | ||
f50c9f76 PB |
157 | Naming Tests |
158 | ------------ | |
159 | ||
160 | The test files are named as: | |
161 | ||
162 | tNNNN-commandname-details.sh | |
163 | ||
164 | where N is a decimal digit. | |
165 | ||
166 | First digit tells the family: | |
167 | ||
168 | 0 - the absolute basics and global stuff | |
169 | 1 - the basic commands concerning database | |
170 | 2 - the basic commands concerning the working tree | |
171 | 3 - the other basic commands (e.g. ls-files) | |
172 | 4 - the diff commands | |
173 | 5 - the pull and exporting commands | |
174 | 6 - the revision tree commands (even e.g. merge-base) | |
8f4a9b62 | 175 | 7 - the porcelainish commands concerning the working tree |
8757749e JN |
176 | 8 - the porcelainish commands concerning forensics |
177 | 9 - the git tools | |
f50c9f76 PB |
178 | |
179 | Second digit tells the particular command we are testing. | |
180 | ||
181 | Third digit (optionally) tells the particular switch or group of switches | |
182 | we are testing. | |
183 | ||
77656600 JH |
184 | If you create files under t/ directory (i.e. here) that is not |
185 | the top-level test script, never name the file to match the above | |
186 | pattern. The Makefile here considers all such files as the | |
187 | top-level test script and tries to run all of them. A care is | |
188 | especially needed if you are creating a common test library | |
189 | file, similar to test-lib.sh, because such a library file may | |
190 | not be suitable for standalone execution. | |
191 | ||
f50c9f76 | 192 | |
986aa7f1 JH |
193 | Writing Tests |
194 | ------------- | |
195 | ||
196 | The test script is written as a shell script. It should start | |
197 | with the standard "#!/bin/sh" with copyright notices, and an | |
198 | assignment to variable 'test_description', like this: | |
199 | ||
200 | #!/bin/sh | |
201 | # | |
202 | # Copyright (c) 2005 Junio C Hamano | |
203 | # | |
204 | ||
14cd1ff3 | 205 | test_description='xxx test (option --frotz) |
986aa7f1 JH |
206 | |
207 | This test registers the following structure in the cache | |
208 | and tries to run git-ls-files with option --frotz.' | |
209 | ||
f50c9f76 | 210 | |
986aa7f1 JH |
211 | Source 'test-lib.sh' |
212 | -------------------- | |
213 | ||
214 | After assigning test_description, the test script should source | |
215 | test-lib.sh like this: | |
216 | ||
217 | . ./test-lib.sh | |
218 | ||
219 | This test harness library does the following things: | |
220 | ||
221 | - If the script is invoked with command line argument --help | |
222 | (or -h), it shows the test_description and exits. | |
223 | ||
e1ca1c9d ÆAB |
224 | - Creates an empty test directory with an empty .git/objects database |
225 | and chdir(2) into it. This directory is 't/trash | |
226 | directory.$test_name_without_dotsh', with t/ subject to change by | |
227 | the --root option documented above. | |
986aa7f1 JH |
228 | |
229 | - Defines standard test helper functions for your scripts to | |
230 | use. These functions are designed to make all scripts behave | |
231 | consistently when command line arguments --verbose (or -v), | |
232 | --debug (or -d), and --immediate (or -i) is given. | |
233 | ||
20873f45 ÆAB |
234 | Do's, don'ts & things to keep in mind |
235 | ------------------------------------- | |
236 | ||
6fd45295 | 237 | Here are a few examples of things you probably should and shouldn't do |
20873f45 ÆAB |
238 | when writing tests. |
239 | ||
240 | Do: | |
241 | ||
6fd45295 | 242 | - Put all code inside test_expect_success and other assertions. |
20873f45 ÆAB |
243 | |
244 | Even code that isn't a test per se, but merely some setup code | |
6fd45295 | 245 | should be inside a test assertion. |
20873f45 ÆAB |
246 | |
247 | - Chain your test assertions | |
248 | ||
249 | Write test code like this: | |
250 | ||
251 | git merge foo && | |
252 | git push bar && | |
253 | test ... | |
254 | ||
255 | Instead of: | |
256 | ||
257 | git merge hla | |
258 | git push gh | |
259 | test ... | |
260 | ||
261 | That way all of the commands in your tests will succeed or fail. If | |
bdcaa325 JN |
262 | you must ignore the return value of something (e.g., the return |
263 | after unsetting a variable that was already unset is unportable) it's | |
264 | best to indicate so explicitly with a semicolon: | |
20873f45 | 265 | |
bdcaa325 | 266 | unset HLAGH; |
20873f45 ÆAB |
267 | git merge hla && |
268 | git push gh && | |
269 | test ... | |
270 | ||
0c357544 ÆAB |
271 | - Check the test coverage for your tests. See the "Test coverage" |
272 | below. | |
273 | ||
20873f45 ÆAB |
274 | Don't: |
275 | ||
276 | - exit() within a <script> part. | |
277 | ||
278 | The harness will catch this as a programming error of the test. | |
279 | Use test_done instead if you need to stop the tests early (see | |
280 | "Skipping tests" below). | |
281 | ||
282 | - Break the TAP output | |
283 | ||
6fd45295 JH |
284 | The raw output from your test may be interpreted by a TAP harness. TAP |
285 | harnesses will ignore everything they don't know about, but don't step | |
286 | on their toes in these areas: | |
20873f45 ÆAB |
287 | |
288 | - Don't print lines like "$x..$y" where $x and $y are integers. | |
289 | ||
290 | - Don't print lines that begin with "ok" or "not ok". | |
291 | ||
6fd45295 | 292 | TAP harnesses expect a line that begins with either "ok" and "not |
20873f45 ÆAB |
293 | ok" to signal a test passed or failed (and our harness already |
294 | produces such lines), so your script shouldn't emit such lines to | |
295 | their output. | |
296 | ||
297 | You can glean some further possible issues from the TAP grammar | |
298 | (see http://search.cpan.org/perldoc?TAP::Parser::Grammar#TAP_Grammar) | |
299 | but the best indication is to just run the tests with prove(1), | |
300 | it'll complain if anything is amiss. | |
301 | ||
302 | Keep in mind: | |
303 | ||
6fd45295 | 304 | - Inside <script> part, the standard output and standard error |
20873f45 ÆAB |
305 | streams are discarded, and the test harness only reports "ok" or |
306 | "not ok" to the end user running the tests. Under --verbose, they | |
307 | are shown to help debugging the tests. | |
308 | ||
309 | ||
b5500d16 ÆAB |
310 | Skipping tests |
311 | -------------- | |
312 | ||
313 | If you need to skip all the remaining tests you should set skip_all | |
314 | and immediately call test_done. The string you give to skip_all will | |
315 | be used as an explanation for why the test was skipped. for instance: | |
316 | ||
317 | if ! test_have_prereq PERL | |
318 | then | |
319 | skip_all='skipping perl interface tests, perl not available' | |
320 | test_done | |
321 | fi | |
14cd1ff3 | 322 | |
986aa7f1 JH |
323 | End with test_done |
324 | ------------------ | |
325 | ||
326 | Your script will be a sequence of tests, using helper functions | |
327 | from the test harness library. At the end of the script, call | |
328 | 'test_done'. | |
329 | ||
330 | ||
331 | Test harness library | |
332 | -------------------- | |
333 | ||
334 | There are a handful helper functions defined in the test harness | |
335 | library for your script to use. | |
336 | ||
9a897893 | 337 | - test_expect_success [<prereq>] <message> <script> |
986aa7f1 | 338 | |
9a897893 | 339 | Usually takes two strings as parameter, and evaluates the |
986aa7f1 JH |
340 | <script>. If it yields success, test is considered |
341 | successful. <message> should state what it is testing. | |
342 | ||
343 | Example: | |
344 | ||
345 | test_expect_success \ | |
346 | 'git-write-tree should be able to write an empty tree.' \ | |
347 | 'tree=$(git-write-tree)' | |
348 | ||
9a897893 ÆAB |
349 | If you supply three parameters the first will be taken to be a |
350 | prerequisite, see the test_set_prereq and test_have_prereq | |
351 | documentation below: | |
352 | ||
353 | test_expect_success TTY 'git --paginate rev-list uses a pager' \ | |
354 | ' ... ' | |
355 | ||
93a57246 ÆAB |
356 | You can also supply a comma-separated list of prerequisites, in the |
357 | rare case where your test depends on more than one: | |
358 | ||
359 | test_expect_success PERL,PYTHON 'yo dawg' \ | |
360 | ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" ' | |
361 | ||
9a897893 | 362 | - test_expect_failure [<prereq>] <message> <script> |
986aa7f1 | 363 | |
41ac414e JH |
364 | This is NOT the opposite of test_expect_success, but is used |
365 | to mark a test that demonstrates a known breakage. Unlike | |
366 | the usual test_expect_success tests, which say "ok" on | |
367 | success and "FAIL" on failure, this will say "FIXED" on | |
368 | success and "still broken" on failure. Failures from these | |
369 | tests won't cause -i (immediate) to stop. | |
986aa7f1 | 370 | |
9a897893 ÆAB |
371 | Like test_expect_success this function can optionally use a three |
372 | argument invocation with a prerequisite as the first argument. | |
373 | ||
97d9fd92 ÆAB |
374 | - test_expect_code [<prereq>] <code> <message> <script> |
375 | ||
376 | Analogous to test_expect_success, but pass the test if it exits | |
377 | with a given exit <code> | |
378 | ||
379 | test_expect_code 1 'Merge with d/f conflicts' 'git merge "merge msg" B master' | |
380 | ||
986aa7f1 JH |
381 | - test_debug <script> |
382 | ||
383 | This takes a single argument, <script>, and evaluates it only | |
384 | when the test script is started with --debug command line | |
385 | argument. This is primarily meant for use during the | |
386 | development of a new test script. | |
387 | ||
388 | - test_done | |
389 | ||
390 | Your test script must have test_done at the end. Its purpose | |
391 | is to summarize successes and failures in the test script and | |
392 | exit with an appropriate error code. | |
393 | ||
00884968 JS |
394 | - test_tick |
395 | ||
396 | Make commit and tag names consistent by setting the author and | |
397 | committer times to defined stated. Subsequent calls will | |
398 | advance the times by a fixed amount. | |
399 | ||
400 | - test_commit <message> [<filename> [<contents>]] | |
401 | ||
402 | Creates a commit with the given message, committing the given | |
403 | file with the given contents (default for both is to reuse the | |
404 | message string), and adds a tag (again reusing the message | |
405 | string as name). Calls test_tick to make the SHA-1s | |
406 | reproducible. | |
407 | ||
408 | - test_merge <message> <commit-or-tag> | |
409 | ||
410 | Merges the given rev using the given message. Like test_commit, | |
411 | creates a tag and calls test_tick before committing. | |
986aa7f1 | 412 | |
9a897893 ÆAB |
413 | - test_set_prereq SOME_PREREQ |
414 | ||
415 | Set a test prerequisite to be used later with test_have_prereq. The | |
be53deef ÆAB |
416 | test-lib will set some prerequisites for you, see the |
417 | "Prerequisites" section below for a full list of these. | |
418 | ||
419 | Others you can set yourself and use later with either | |
420 | test_have_prereq directly, or the three argument invocation of | |
421 | test_expect_success and test_expect_failure. | |
9a897893 ÆAB |
422 | |
423 | - test_have_prereq SOME PREREQ | |
424 | ||
425 | Check if we have a prerequisite previously set with | |
426 | test_set_prereq. The most common use of this directly is to skip | |
427 | all the tests if we don't have some essential prerequisite: | |
428 | ||
429 | if ! test_have_prereq PERL | |
430 | then | |
431 | skip_all='skipping perl interface tests, perl not available' | |
432 | test_done | |
433 | fi | |
434 | ||
2fac6a4b ÆAB |
435 | - test_external [<prereq>] <message> <external> <script> |
436 | ||
437 | Execute a <script> with an <external> interpreter (like perl). This | |
438 | was added for tests like t9700-perl-git.sh which do most of their | |
439 | work in an external test script. | |
440 | ||
441 | test_external \ | |
442 | 'GitwebCache::*FileCache*' \ | |
443 | "$PERL_PATH" "$TEST_DIRECTORY"/t9503/test_cache_interface.pl | |
444 | ||
445 | If the test is outputting its own TAP you should set the | |
446 | test_external_has_tap variable somewhere before calling the first | |
447 | test_external* function. See t9700-perl-git.sh for an example. | |
448 | ||
449 | # The external test will outputs its own plan | |
450 | test_external_has_tap=1 | |
451 | ||
452 | - test_external_without_stderr [<prereq>] <message> <external> <script> | |
453 | ||
454 | Like test_external but fail if there's any output on stderr, | |
455 | instead of checking the exit code. | |
456 | ||
457 | test_external_without_stderr \ | |
458 | 'Perl API' \ | |
459 | "$PERL_PATH" "$TEST_DIRECTORY"/t9700/test.pl | |
460 | ||
c9667456 JN |
461 | - test_must_fail <git-command> |
462 | ||
463 | Run a git command and ensure it fails in a controlled way. Use | |
971ecbd1 BC |
464 | this instead of "! <git-command>". When git-command dies due to a |
465 | segfault, test_must_fail diagnoses it as an error; "! <git-command>" | |
466 | treats it as just another expected failure, which would let such a | |
467 | bug go unnoticed. | |
c9667456 JN |
468 | |
469 | - test_might_fail <git-command> | |
470 | ||
471 | Similar to test_must_fail, but tolerate success, too. Use this | |
472 | instead of "<git-command> || :" to catch failures due to segv. | |
473 | ||
474 | - test_cmp <expected> <actual> | |
475 | ||
476 | Check whether the content of the <actual> file matches the | |
477 | <expected> file. This behaves like "cmp" but produces more | |
478 | helpful output when the test is run with "-v" option. | |
479 | ||
480 | - test_when_finished <script> | |
481 | ||
482 | Prepend <script> to a list of commands to run to clean up | |
483 | at the end of the current test. If some clean-up command | |
484 | fails, the test will not pass. | |
485 | ||
486 | Example: | |
487 | ||
488 | test_expect_success 'branch pointing to non-commit' ' | |
489 | git rev-parse HEAD^{tree} >.git/refs/heads/invalid && | |
490 | test_when_finished "git update-ref -d refs/heads/invalid" && | |
491 | ... | |
492 | ' | |
493 | ||
be53deef ÆAB |
494 | Prerequisites |
495 | ------------- | |
496 | ||
497 | These are the prerequisites that the test library predefines with | |
498 | test_have_prereq. | |
499 | ||
500 | See the prereq argument to the test_* functions in the "Test harness | |
501 | library" section above and the "test_have_prereq" function for how to | |
502 | use these, and "test_set_prereq" for how to define your own. | |
503 | ||
504 | - PERL & PYTHON | |
505 | ||
506 | Git wasn't compiled with NO_PERL=YesPlease or | |
507 | NO_PYTHON=YesPlease. Wrap any tests that need Perl or Python in | |
508 | these. | |
509 | ||
510 | - POSIXPERM | |
511 | ||
512 | The filesystem supports POSIX style permission bits. | |
513 | ||
514 | - BSLASHPSPEC | |
515 | ||
516 | Backslashes in pathspec are not directory separators. This is not | |
517 | set on Windows. See 6fd1106a for details. | |
518 | ||
519 | - EXECKEEPSPID | |
520 | ||
521 | The process retains the same pid across exec(2). See fb9a2bea for | |
522 | details. | |
523 | ||
524 | - SYMLINKS | |
525 | ||
526 | The filesystem we're on supports symbolic links. E.g. a FAT | |
527 | filesystem doesn't support these. See 704a3143 for details. | |
2fac6a4b | 528 | |
c91cfd19 ÆAB |
529 | - SANITY |
530 | ||
531 | Test is not run by root user, and an attempt to write to an | |
532 | unwritable file is expected to fail correctly. | |
533 | ||
986aa7f1 JH |
534 | Tips for Writing Tests |
535 | ---------------------- | |
536 | ||
537 | As with any programming projects, existing programs are the best | |
538 | source of the information. However, do _not_ emulate | |
539 | t0000-basic.sh when writing your tests. The test is special in | |
540 | that it tries to validate the very core of GIT. For example, it | |
541 | knows that there will be 256 subdirectories under .git/objects/, | |
542 | and it knows that the object ID of an empty tree is a certain | |
543 | 40-byte string. This is deliberately done so in t0000-basic.sh | |
544 | because the things the very basic core test tries to achieve is | |
545 | to serve as a basis for people who are changing the GIT internal | |
546 | drastically. For these people, after making certain changes, | |
547 | not seeing failures from the basic test _is_ a failure. And | |
548 | such drastic changes to the core GIT that even changes these | |
549 | otherwise supposedly stable object IDs should be accompanied by | |
550 | an update to t0000-basic.sh. | |
551 | ||
552 | However, other tests that simply rely on basic parts of the core | |
553 | GIT working properly should not have that level of intimate | |
554 | knowledge of the core GIT internals. If all the test scripts | |
555 | hardcoded the object IDs like t0000-basic.sh does, that defeats | |
556 | the purpose of t0000-basic.sh, which is to isolate that level of | |
557 | validation in one place. Your test also ends up needing | |
558 | updating when such a change to the internal happens, so do _not_ | |
559 | do it and leave the low level of validation to t0000-basic.sh. | |
d15e9ebc | 560 | |
0c357544 ÆAB |
561 | Test coverage |
562 | ------------- | |
563 | ||
564 | You can use the coverage tests to find code paths that are not being | |
565 | used or properly exercised yet. | |
566 | ||
567 | To do that, run the coverage target at the top-level (not in the t/ | |
568 | directory): | |
569 | ||
570 | make coverage | |
571 | ||
572 | That'll compile Git with GCC's coverage arguments, and generate a test | |
573 | report with gcov after the tests finish. Running the coverage tests | |
574 | can take a while, since running the tests in parallel is incompatible | |
575 | with GCC's coverage mode. | |
576 | ||
577 | After the tests have run you can generate a list of untested | |
578 | functions: | |
579 | ||
580 | make coverage-untested-functions | |
581 | ||
582 | You can also generate a detailed per-file HTML report using the | |
583 | Devel::Cover module. To install it do: | |
584 | ||
585 | # On Debian or Ubuntu: | |
586 | sudo aptitude install libdevel-cover-perl | |
587 | ||
588 | # From the CPAN with cpanminus | |
589 | curl -L http://cpanmin.us | perl - --sudo --self-upgrade | |
590 | cpanm --sudo Devel::Cover | |
591 | ||
592 | Then, at the top-level: | |
593 | ||
594 | make cover_db_html | |
595 | ||
596 | That'll generate a detailed cover report in the "cover_db_html" | |
597 | directory, which you can then copy to a webserver, or inspect locally | |
598 | in a browser. | |
599 | ||
d15e9ebc ÆAB |
600 | Smoke testing |
601 | ------------- | |
602 | ||
603 | The Git test suite has support for smoke testing. Smoke testing is | |
604 | when you submit the results of a test run to a central server for | |
605 | analysis and aggregation. | |
606 | ||
607 | Running a smoke tester is an easy and valuable way of contributing to | |
608 | Git development, particularly if you have access to an uncommon OS on | |
609 | obscure hardware. | |
610 | ||
611 | After building Git you can generate a smoke report like this in the | |
612 | "t" directory: | |
613 | ||
614 | make clean smoke | |
615 | ||
616 | You can also pass arguments via the environment. This should make it | |
617 | faster: | |
618 | ||
619 | GIT_TEST_OPTS='--root=/dev/shm' TEST_JOBS=10 make clean smoke | |
620 | ||
621 | The "smoke" target will run the Git test suite with Perl's | |
622 | "TAP::Harness" module, and package up the results in a .tar.gz archive | |
623 | with "TAP::Harness::Archive". The former is included with Perl v5.10.1 | |
624 | or later, but you'll need to install the latter from the CPAN. See the | |
625 | "Test coverage" section above for how you might do that. | |
626 | ||
627 | Once the "smoke" target finishes you'll see a message like this: | |
628 | ||
629 | TAP Archive created at <path to git>/t/test-results/git-smoke.tar.gz | |
630 | ||
631 | To upload the smoke report you need to have curl(1) installed, then | |
632 | do: | |
633 | ||
634 | make smoke_report | |
635 | ||
636 | To upload the report anonymously. Hopefully that'll return something | |
637 | like "Reported #7 added.". | |
638 | ||
639 | If you're going to be uploading reports frequently please request a | |
640 | user account by E-Mailing gitsmoke@v.nix.is. Once you have a username | |
641 | and password you'll be able to do: | |
642 | ||
643 | SMOKE_USERNAME=<username> SMOKE_PASSWORD=<password> make smoke_report | |
644 | ||
e38efac8 ÆAB |
645 | You can also add an additional comment to attach to the report, and/or |
646 | a comma separated list of tags: | |
647 | ||
648 | SMOKE_USERNAME=<username> SMOKE_PASSWORD=<password> \ | |
649 | SMOKE_COMMENT=<comment> SMOKE_TAGS=<tags> \ | |
650 | make smoke_report | |
651 | ||
d15e9ebc ÆAB |
652 | Once the report is uploaded it'll be made available at |
653 | http://smoke.git.nix.is, here's an overview of Recent Smoke Reports | |
654 | for Git: | |
655 | ||
656 | http://smoke.git.nix.is/app/projects/smoke_reports/1 | |
657 | ||
658 | The reports will also be mirrored to GitHub every few hours: | |
659 | ||
660 | http://github.com/gitsmoke/smoke-reports | |
661 | ||
662 | The Smolder SQLite database is also mirrored and made available for | |
663 | download: | |
664 | ||
665 | http://github.com/gitsmoke/smoke-database | |
666 | ||
667 | Note that the database includes hashed (with crypt()) user passwords | |
668 | and E-Mail addresses. Don't use a valuable password for the smoke | |
669 | service if you have an account, or an E-Mail address you don't want to | |
670 | be publicly known. The user accounts are just meant to be convenient | |
671 | labels, they're not meant to be secure. |