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