Generating a Coverage Report #

A coverage report is a summary of how good and how much the productive code is covered by test cases. The report can reference one or more packages containing unit tests. The coverage is a percentaged value indicating the percentage of code lines covered by tests. The best case is 100% where every line of code is executed by a test.

The coverage report for the Trivial Tickets Web Server and Command-line Tool can be easily generated by the script coverage_report.sh. It executes the tests for the named packages or for all sub-packages by default using go test and creates a coverage report in the HTML format which is opened in the user’s default browser. The report can be configured by various command-line options which are presented below. For example, a summary of the coverage of each function can be generated by the --functions option instead of an output HTML file. The coverage mode can be altered by the --coverage-mode option.

Usage #

coverage_report.sh [option(s)] [--] [package] ...

Generate a coverage report for the applied packages or by default for all sub-packages using ./.... The results are displayed in the specified output format or by default in HTML opened in the default browser.

Options #

The following options can be used to modify the test and output settings. Mandatory options to long options are also mandatory to short options.

-c, --checks=<LIST> #

Specify code checks to be run by go vet before the actual tests. LIST is a comma-separated list of check names. Special values of LIST include:

• all: run all checks
• default: selects all checks that are assumed to be always worth
• off: no checks are done by go vet

The default for LIST is default. Look at the options documented at go tool vet -help for a complete list of checks.

-m, --coverage-mode=<MODE> #

Set the mode for coverage analysis for the packages being tested. MODE can be one of the following:

• set: test which statements run
• count: test how often a statement runs
• atomic: count runs of a statement, but correct in multithreaded tests (significantly more expensive)

The default for MODE is atomic.

-p, --coverage-profile=<FILE> #

Write the coverage profile generated by go test to FILE. If --output-directory is supplied the file is written to the specified output directory.

-f, --functions #

Generate coverage information for each function in the applied packages. Overrides --html.

-h, --help #

Display a help message and exit.

-H, --html #

Generate a HTML representation of the coverage profile and open it in the default web browser unless --output-file is specified in which case the HTML is written to the specified file. Overrides --functions.

-d, --output-directory=<DIR> #

Write the coverage report and the output file to the applied directory. DIR must exist and needs to be a directory.

-o, --output-file=<FILE> #

Write the outgoing coverage report from go tool cover to FILE. This can be either a plain text file if functions is supplied, or a HTML file if --html was given. The FILE should not exist yet, otherwise it is going to be overwritten. The leading directory, if any, is stripped if --output-directory is given.

--preserve-profile #

Do not remove the coverage profile after the output file has been generated.

-r, --race #

Examine the tests and search for race conditions in parallelized tests or code and report warnings, if any.

-v, --verbose #

Print information for each executed test such as test logs and results.

Default settings #

By default, the coverage profile is named coverage.txt and is written to the directory in which the tests were executed. The --output-directory option can change the location, whereas the directory must exist. Note that the coverage results are not generated if one of the tests fails.

The default coverage mode is atomic which is a complete analysis of the significance of the executed statements. It counts the number of executions for each statement and is also correct for tests which run on multiple go routines. By default, all checks assumed to be beneficial are run before the actual tests.

The option --html is assumed if none of --html or --functions is specified. These options override each other. If --output-file is not specified, the HTML output will be shown in the default web browser.