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. This happens when returning to the top of a loop. For detailed examples of how branch coverage works in loops and other control flow constructs, see Examples of missing branches.

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`