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