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