| Author: | Ned Batchelder <ned@nedbatchelder.com> |
|---|---|
| Author: | Ben Finney <ben+python@benfinney.id.au> |
| Date: | 2021-01-24 |
| Copyright: | Apache 2.0 license, attribution and disclaimer required. |
| Manual section: | 1 |
| Manual group: | Coverage.py |
python-coverage command [ option ... ]
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.
- python-coverage lcov
- Create an LCOV 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 original input 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 original coverage data files.
- -q, --quiet
- Don't print messages about what is happening.
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.
- -q, --quiet
- Don't print messages about what is happening.
- --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.
- -q, --quiet
- Don't print messages about what is happening.
- --show-contexts
- Include information about the contexts that executed each line.
lcov [ option ... ] [ MODULE ... ]
Create an LCOV report of the coverage results.
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.
- -o OUTFILE
- Write the LCOV report to OUTFILE. Defaults to
coverage.lcov.- --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.
- -q, --quiet
- Don't print messages about what is happening.
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 LIBS
- Properly measure code using a concurrency library. Valid values are: thread, gevent, greenlet, eventlet, multiprocessing, or a comma-list of them.
- --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.- -q, --quiet
- Don't print messages about what is happening.
- --skip-empty
- Skip files with no code.
COVERAGE_FILE
Path to the file where coverage measurements are collected to and
reported from. Default: .coverage in 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 Ben Finney <ben+python@benfinney.id.au>.