[run]
disable_warnings = no-data-collected
[tool.coverage.run]
disable_warnings = ["no-data-collected"]
[coverage:run]
disable_warnings = no-data-collected
Data file
Coverage.py collects execution data in a file called “.coverage”. If need be,
you can set a new file name with the COVERAGE_FILE environment variable.
This can include a path to another directory.
By default, each run of your program starts with an empty data set. If you need
to run your program multiple times to get complete data (for example, because
you need to supply different options), you can accumulate data across runs with
the --append flag on the run command.
Combining data files: coverage combine
Often test suites are run under different conditions, for example, with
different versions of Python, or dependencies, or on different operating
systems. In these cases, you can collect coverage data for each test run, and
then combine all the separate data files into one combined file for reporting.
The combine command reads a number of separate data files, matches the data
by source file name, and writes a combined data file with all of the data.
Coverage normally writes data to a filed named “.coverage”. The run
--parallel-mode switch (or [run] parallel=True configuration option)
tells coverage to expand the file name to include machine name, process id, and
a random number so that every data file is distinct:
.coverage.Neds-MacBook-Pro.local.88335.316857
.coverage.Geometer.8044.799674
You can also define a new data file name with the [run] data_file option.
Once you have created a number of these files, you can copy them all to a
single directory, and use the combine command to combine them into one
.coverage data file:
$ coverage combine
You can also name directories or files to be combined on the command line:
$ coverage combine data1.dat windows_data_files/
Coverage.py will collect the data from those places and combine them. The
current directory isn’t searched if you use command-line arguments. If you
also want data from the current directory, name it explicitly on the command
line.
When coverage.py combines data files, it looks for files named the same as the
data file (defaulting to “.coverage”), with a dotted suffix. Here are some
examples of data files that can be combined:
.coverage.machine1
.coverage.20120807T212300
.coverage.last_good_run.ok
An existing combined data file is ignored and re-written. If you want to use
combine to accumulate results into the .coverage data file over a number of
runs, use the --append switch on the combine command. This behavior
was the default before version 4.2.
If any of the data files can’t be read, coverage.py will print a warning
indicating the file and the problem.
The original input data files are deleted once they’ve been combined. If you
want to keep those files, use the --keep command-line option.
$ coverage combine --help
Usage: coverage combine [options] <path1> <path2> ... <pathN>
Combine data from multiple coverage files. The combined results are written to
a single file representing the union of the data. The positional arguments are
data files or directories containing data files. If no paths are provided,
data files in the default data file's directory are combined.
Options:
-a, --append Append coverage data to .coverage, otherwise it starts
clean each time.
--data-file=DATAFILE Base name of the data files to operate on. Defaults to
'.coverage'. [env: COVERAGE_FILE]
--keep Keep original coverage files, otherwise they are
deleted.
-q, --quiet Don't print messages about what is happening.
--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]
Re-mapping paths
To combine data for a source file, coverage has to find its data in each of the
data files. Different test runs may run the same source file from different
locations. For example, different operating systems will use different paths
for the same file, or perhaps each Python version is run from a different
subdirectory. Coverage needs to know that different file paths are actually
the same source file for reporting purposes.
You can tell coverage.py how different source locations relate with a
[paths] section in your configuration file (see [paths]).
It might be more convenient to use the [run] relative_files
setting to store relative file paths (see relative_files).
If data isn’t combining properly, you can see details about the inner workings
with --debug=pathmap.
Erase data: coverage erase
To erase the collected data, use the erase command:
$ coverage erase --help
Usage: coverage erase [options]
Erase previously collected coverage data.
Options:
--data-file=DATAFILE Base name of the data files to operate on. Defaults to
'.coverage'. [env: COVERAGE_FILE]
--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]
If your configuration file indicates parallel data collection, erase will
remove all of the data files.
Reporting
Coverage.py provides a few styles of reporting, with the report, html,
annotate, json, lcov, and xml commands. They share a number
of common options.
The command-line arguments are module or file names to report on, if you’d like
to report on a subset of the data collected.
The --include and --omit flags specify lists of file name patterns.
They control which files to report on, and are described in more detail in
Specifying source files.
The -i or --ignore-errors switch tells coverage.py to ignore problems
encountered trying to find source files to report on. This can be useful if
some files are missing, or if your Python execution is tricky enough that file
names are synthesized without real source files.
If you provide a --fail-under value, the total percentage covered will be
compared to that value. If it is less, the command will exit with a status
code of 2, indicating that the total coverage was less than your target. This
can be used as part of a pass/fail condition, for example in a continuous
integration server. This option isn’t available for annotate.
These options can also be set in your .coveragerc file. See
Configuration: [report].
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].
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].
XML reporting: coverage xml
The xml command writes coverage data to a “coverage.xml” file in a format
compatible with Cobertura.
$ coverage xml --help
Usage: coverage xml [options] [modules]
Generate an XML report of coverage results.
Options:
--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.
-o OUTFILE Write the XML report to this file. Defaults to
'coverage.xml'
-q, --quiet Don't print messages about what is happening.
--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]
You can specify the name of the output file with the -o
switch.
Other common reporting options are described above in Reporting.
To include complete file paths in the output file, rather than just
the file name, use [include] vs [source] in your “.coveragerc” file.
For example, use this:
[run]
include =
foo/*
bar/*
which will result in
<class filename="bar/hello.py">
<class filename="bar/baz/hello.py">
<class filename="foo/hello.py">
in place of this:
[run]
source =
which may result in
<class filename="hello.py">
<class filename="baz/hello.py">
These options can also be set in your .coveragerc file. See
Configuration: [xml].
JSON reporting: coverage json
The json command writes coverage data to a “coverage.json” file.
$ coverage json --help
Usage: coverage json [options] [modules]
Generate a JSON report of coverage results.
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.
-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.
-o OUTFILE Write the JSON report to this file. Defaults to
'coverage.json'
--pretty-print Format the JSON for human readers.
-q, --quiet Don't print messages about what is happening.
--show-contexts Show contexts for covered lines.
--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]
You can specify the name of the output file with the -o switch. The JSON
can be nicely formatted by specifying the --pretty-print switch.
Other common reporting options are described above in Reporting.
These options can also be set in your .coveragerc file. See
Configuration: [json].
LCOV reporting: coverage lcov
The lcov command writes coverage data to a “coverage.lcov” file.
$ coverage lcov --help
Usage: coverage lcov [options] [modules]
Generate an LCOV report of coverage results.
Options:
--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.
-o OUTFILE Write the LCOV report to this file. Defaults to
'coverage.lcov'
--omit=PAT1,PAT2,... Omit files whose paths match one of these patterns.
Accepts shell-style wildcards, which must be quoted.
-q, --quiet Don't print messages about what is happening.
--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]
Common reporting options are described above in Reporting.
Also see Configuration: [lcov].
Added in version 6.3.
Text annotation: coverage annotate
The annotate command has been obsoleted by more modern reporting tools,
including the html command.
The annotate command produces a text annotation of your source code. With
a -d argument specifying an output directory, each Python file becomes a
text file in that directory. Without -d, the files are written into the
same directories as the original Python files.
Coverage status for each line of source is indicated with a character prefix:
> executed
! missing (not executed)
- excluded
For example:
# A simple function, never called with x==1
> def h(x):
"""Silly function."""
- if 0: # pragma: no cover
- pass
> if x == 1:
! a = 1
> else:
> a = 2
$ coverage annotate --help
Usage: coverage annotate [options] [modules]
Make annotated copies of the given files, marking statements that are executed
with > and statements that are missed with !.
Options:
-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]
-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.
--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]
Other common reporting options are described above in Reporting.
Diagnostics: coverage debug
The debug command shows internal information to help diagnose problems.
If you are reporting a bug about coverage.py, including the output of this
command can often help:
$ coverage debug sys > please_attach_to_bug_report.txt
A few types of information are available:
config: show coverage’s configuration
sys: show system configuration
data: show a summary of the collected coverage data
premain: show the call stack invoking coverage
pybehave: show internal flags describing Python behavior
$ coverage debug --help
Usage: coverage debug <topic>
Display information about the internals of coverage.py, for diagnosing
problems. Topics are: 'data' to show a summary of the collected data; 'sys' to
show installation information; 'config' to show the configuration; 'premain'
to show what is calling coverage; 'pybehave' to show internal flags describing
Python behavior.
Options:
--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]
--debug
The --debug option is also available on all commands. It instructs
coverage.py to log internal details of its operation, to help with diagnosing
problems. It takes a comma-separated list of options, each indicating a facet
of operation to log:
callers: annotate each debug message with a stack trace of the callers
to that point.
config: before starting, dump all the configuration
values.
dataio: log when reading or writing any data file.
dataop: log a summary of data being added to CoverageData objects.
dataop2: when used with debug=dataop, log the actual data being added
to CoverageData objects.
lock: log operations acquiring locks in the data layer.
multiproc: log the start and stop of multiprocessing processes.
pathmap: log the remapping of paths that happens during coverage
combine. See [paths].
pid: annotate all warnings and debug output with the process and thread
plugin: print information about plugin operations.
process: show process creation information, and changes in the current
directory. This also writes a time stamp and command arguments into the data
file.
pybehave: show the values of internal flags describing the
behavior of the current version of Python.
pytest: indicate the name of the current pytest test when it changes.
self: annotate each debug message with the object printing the message.
sql: log the SQL statements used for recording data.
sqldata: when used with debug=sql, also log the full data being used
in SQL statements.
sys: before starting, dump all the system and environment information,
as with coverage debug sys.
trace: print every decision about whether to trace a file or not. For
files not being traced, the reason is also given.
Debug options can also be set with the COVERAGE_DEBUG environment variable,
a comma-separated list of these options, or in the [run] debug
section of the .coveragerc file.
The debug output goes to stderr, unless the [run] debug_file
setting or the COVERAGE_DEBUG_FILE environment variable names a different
file, which will be appended to. This can be useful because many test runners
capture output, which could hide important details. COVERAGE_DEBUG_FILE
accepts the special names stdout and stderr to write to those
destinations.
