- Author
Ned Batchelder <ned@nedbatchelder.com>
- Author
- Date
2021-01-24
- Copyright
Apache 2.0 license, attribution and disclaimer required.
- Manual section
1
- Manual group
Coverage.py
python-coverage help [ command ]
python-coverage executes a Python program and measures which of its statements are executed and which are not, and reports these coverage measurements.
- python-coverage annotate
Annotate source files with execution information.
- python-coverage combine
Combine a number of data files.
- python-coverage debug
Display information about the internals of coverage.py.
- python-coverage erase
Erase previously collected coverage data.
- python-coverage help
Get help on using coverage.py.
- python-coverage html
Create an HTML report.
- python-coverage json
Create a JSON report of coverage results.
- python-coverage report
Report coverage stats on modules.
- python-coverage run
Run a Python program and measure code execution.
- python-coverage xml
Create an XML report of coverage results.
- --help, -h
Describe how to use coverage.py, in general or a command.
- --rcfile RCFILE
Specify configuration file RCFILE. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
- --debug DEBUGOPT,...
Debug options DEBUGOPT, separated by commas.
annotate [ option ... ]
Options:
- -d DIR, --directory=`DIR`
Write the output files to DIR.
- -i, --ignore-errors
Ignore errors while reading source files.
- --include PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
combine [ option ... ] [ PATH ... ]
Combine data from multiple coverage files collected with
run -p. The combined results are written to a single file representing the union of the data. Unless --keep is provided the combined coverage files are deleted.If PATH is specified, they are files or directories containing data to be combined.
Options:
- --append
Append coverage data to .coverage, otherwise it starts clean each time.
- --keep
Keep combined coverage file.
debug TOPIC ...
Display information about the internals of coverage.py, for diagnosing problems.
Topics are:
datato show a summary of the collected data;systo show installation information;configto show the configuration;premainto show what is calling coverage.
erase
Erase previously collected coverage data.
help [ command ]
Describe how to use coverage.py.
html [ option ... ] [ MODULE ... ]
Create an HTML report of the coverage of each MODULE file. Each file gets its own page, with the source decorated to show executed, excluded, and missed lines.
Options:
- --contexts PAT [ , ... ]
Only include contexts that match one of the regex patterns.
- -d DIR, --directory DIR
Write the output files to DIR.
- --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 PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
- --precision N
Number of digits after the decimal point to display for reported coverage percentages.
- --show-contexts
Annotate lines with the contexts that executed them.
- --skip-covered
Skip files with 100% coverage.
- --no-skip-covered
Disable
--skip-covered.- --skip-empty
Skip files with no code.
- --title TITLE
Use the text string TITLE as the title on the HTML.
json [ option ... ] [ MODULE ... ]
Generate a JSON report of coverage results.
- --contexts PAT [ , ... ]
Only include contexts that match one of the regex patterns.
- --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 PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- -o OUTFILE
Write the JSON report to OUTFILE. Defaults to
coverage.json.- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
- --pretty-print
Format the JSON for human readers.
- --show-contexts
Include information about the contexts that executed each line.
report [ option ... ] [ MODULE ... ]
Report coverage statistics on each MODULE.
Options:
- --contexts PAT [ , ... ]
Only include contexts that match one of the regex patterns.
- --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 PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
- -m, --show-missing
Show line numbers of statements in each module that weren't executed.
- --precision N
Number of digits after the decimal point to display for reported coverage percentages.
- --skip-covered
Skip files with 100% coverage.
- --no-skip-covered
Disable
--skip-covered.- --skip-empty
Skip files with no code.
- --sort COLUMN
Sort the report by thee named column: name, stmts, miss, branch, brpart, or cover.
run [ options ... ] PROGRAMFILE [ program_options ]
Run a Python program PROGRAMFILE, measuring code execution.
Options:
- -a, --append
Append coverage data to .coverage, otherwise it is started clean with each run.
- --branch
Measure branch coverage in addition to statement coverage.
- --concurrency LIB
Properly measure code using a concurrency library. Valid values are: thread, gevent, greenlet, eventlet, multiprocessing.
- --context CONTEXT
The context label to record for this coverage run.
- --include PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- -m
PROGRAMFILE is interpreted as a module name.
- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
- -L, --pylib
Measure coverage even inside the Python installed library, which isn't done by default.
- -p, --parallel-mode
Append the machine name, process id and random number to the
.coveragedata file name to simplify collecting data from many processes.- --source SOURCE ...
A list of packages or directories of code to be measured.
- --timid
Use a simpler but slower trace method. Try this if you get seemingly impossible results!
xml [ options ... ] [ MODULES ... ]
Generate an XML report of coverage results on each MODULE.
Options:
- --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 PATTERN [ , ... ]
Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted.
- --omit PATTERN [ , ... ]
Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line.
- -o OUTFILE
Write the XML report to OUTFILE. Defaults to
coverage.xml.- --skip-empty
Skip files with no code.
COVERAGE_FILE
Path to the file where coverage measurements are collected to and reported from. Default:
.coveragein the current working directory.
COVERAGE_RCFILE
Path to the configuration file, often named
.coveragerc.
The python-coverage command is a Python program which calls the coverage Python library to do all the work.
It was originally developed by Gareth Rees, and is now developed by Ned Batchelder and many others.
This manual page was written by .