Coverage summary: `coverage report`

The simplest reporting is a textual summary produced with report:

$ coverage report
Name                      Stmts   Miss  Cover
---------------------------------------------
my_program.py                20      4    80%
my_module.py                 15      2    86%
my_other_module.py           56      6    89%
---------------------------------------------
TOTAL                        91     12    87%

For each module executed, the report shows the count of executable statements, the number of those statements missed, and the resulting coverage, expressed as a percentage.

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

Report coverage statistics on modules.

Options:
  --contexts=REGEX1,REGEX2,...
                        Only display data from lines covered in the given
                        contexts. Accepts Python regexes, which must be
                        quoted.
  --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.
  --format=FORMAT       Output format, either text (default), markdown, or
                        total.
  -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.
  --sort=COLUMN         Sort the report by the named column: name, stmts,
                        miss, branch, brpart, or cover. Default is name.
  -m, --show-missing    Show line numbers of statements in each module that
                        weren't executed.
  --skip-covered        Skip files with 100% coverage.
  --no-skip-covered     Disable --skip-covered.
  --skip-empty          Skip files with no code.
  --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 -m flag also shows the line numbers of missing statements:

$ coverage report -m
Name                      Stmts   Miss  Cover   Missing
-------------------------------------------------------
my_program.py                20      4    80%   33-35, 39
my_module.py                 15      2    86%   8, 12
my_other_module.py           56      6    89%   17-23
-------------------------------------------------------
TOTAL                        91     12    87%

If you are using branch coverage, then branch statistics will be reported in the Branch and BrPart (for Partial Branch) columns, the Missing column will detail the missed branches:

$ coverage report -m
Name                      Stmts   Miss Branch BrPart  Cover   Missing
---------------------------------------------------------------------
my_program.py                20      4     10      2    80%   33-35, 36->38, 39
my_module.py                 15      2      3      0    86%   8, 12
my_other_module.py           56      6      5      1    89%   17-23, 40->45
---------------------------------------------------------------------
TOTAL                        91     12     18      3    87%

Ranges of lines are shown with a dash: “17-23” means all lines from 17 to 23 inclusive are missing coverage. Missed branches are shown with an arrow: “40->45” means the branch from line 40 to line 45 is missing. A branch can go backwards in a file, so you might see a branch from a later line to an earlier line, like “55->50”.

You can restrict the report to only certain files by naming them on the command line:

$ coverage report -m my_program.py my_other_module.py
Name                      Stmts   Miss  Cover   Missing
-------------------------------------------------------
my_program.py                20      4    80%   33-35, 39
my_other_module.py           56      6    89%   17-23
-------------------------------------------------------
TOTAL                        76     10    87%

The --skip-covered switch will skip any file with 100% coverage, letting you focus on the files that still need attention. The --no-skip-covered option can be used if needed to see all the files. The --skip-empty switch will skip any file with no executable statements.

If you have recorded contexts, the --contexts option lets you choose which contexts to report on. See Context reporting for details.

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

The --sort option is the name of a column to sort the report by.

The --format option controls the style of the report. --format=text creates plain text tables as shown above. --format=markdown creates Markdown tables. --format=total writes out a single number, the total coverage percentage as shown at the end of the tables, but without a percent sign.

Other common reporting options are described above in Reporting. These options can also be set in your .coveragerc file. See Configuration: [report].

Coverage summary: coverage report

Coverage summary: `coverage report`