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