HTML reporting: coverage html

Coverage.py can annotate your source code to show which lines were executed and which were not. The html command creates an HTML report similar to the report summary, but as an HTML file. Each module name links to the source file decorated to show the status of each line.

Here’s a sample report.

Lines are highlighted: green for executed, red for missing, and gray for excluded. If you’ve used branch coverage, partial branches are yellow. The colored counts at the top of the file are buttons to turn on and off the highlighting.

A number of keyboard shortcuts are available for navigating the report. Click the keyboard icon in the upper right to see the complete list.

$ coverage html --help
Usage: coverage html [options] [modules]

Create an HTML report of the coverage of the files. Each file gets its own
page, with the source decorated to show executed, excluded, and missed lines.

Options:
  --contexts=REGEX1,REGEX2,...
                        Only display data from lines covered in the given
                        contexts. Accepts Python regexes, which must be
                        quoted.
  -d DIR, --directory=DIR
                        Write the output files to DIR.
  --data-file=INFILE    Read coverage data for report generation from this
                        file. Defaults to '.coverage'. [env: COVERAGE_FILE]
  --fail-under=MIN      Exit with a status of 2 if the total coverage is less
                        than MIN.
  -i, --ignore-errors   Ignore errors while reading source files.
  --include=PAT1,PAT2,...
                        Include only files whose paths match one of these
                        patterns. Accepts shell-style wildcards, which must be
                        quoted.
  --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
                        Accepts shell-style wildcards, which must be quoted.
  --precision=N         Number of digits after the decimal point to display
                        for reported coverage percentages.
  -q, --quiet           Don't print messages about what is happening.
  --show-contexts       Show contexts for covered lines.
  --skip-covered        Skip files with 100% coverage.
  --no-skip-covered     Disable --skip-covered.
  --skip-empty          Skip files with no code.
  --title=TITLE         A text string to use as the title on the HTML.
  --debug=OPTS          Debug options, separated by commas. [env:
                        COVERAGE_DEBUG]
  -h, --help            Get help on this command.
  --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                        'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                        tried. [env: COVERAGE_RCFILE]

The title of the report can be set with the title setting in the [html] section of the configuration file, or the --title switch on the command line.

If you prefer a different style for your HTML report, you can provide your own CSS file to apply, by specifying a CSS file in the [html] section of the configuration file. See [html] extra_css for details.

The -d argument specifies an output directory, defaulting to “htmlcov”:

$ coverage html -d coverage_html

Other common reporting options are described above in Reporting.

Generating the HTML report can be time-consuming. Stored with the HTML report is a data file that is used to speed up reporting the next time. If you generate a new report into the same directory, coverage.py will skip generating unchanged pages, making the process faster.

The --skip-covered switch will skip any file with 100% coverage, letting you focus on the files that still need attention. The --skip-empty switch will skip any file with no executable statements.

The --precision option controls the number of digits displayed after the decimal point in coverage percentages, defaulting to none.

If you have recorded contexts, the --contexts option lets you choose which contexts to report on, and the --show-contexts option will annotate lines with the contexts that ran them. See Context reporting for details.

These options can also be set in your .coveragerc file. See Configuration: [html].