Coverage command line usage

history: 20090524T134300, brand new docs. 20090613T164000, final touches for 3.0 20090913T084400, new command line syntax 20091004T170700, changes for 3.1 20091127T200700, changes for 3.2 20100223T200600, changes for 3.3 20100725T211700, updated for 3.4 20110827T212500, updated for 3.5.1, combining aliases 20120119T075600, Added some clarification from George Paci 20120504T091800, Added info about execution warnings, and 3.5.2 stuff. 20120807T211600, Clarified the combine rules. 20121003T074600, Fixed an option reference, https://bitbucket.org/ned/coveragepy/issue/200/documentation-mentions-output-xml-instead 20121117T091000, Added command aliases.

When you install coverage.py, a command-line script simply called coverage is placed in your Python scripts directory. To help with multi-version installs, it will also create either a coverage2 or coverage3 alias, and a coverage-X.Y alias, depending on the version of Python you're using. For example, when installing on Python 2.7, you will be able to use coverage, coverage2, or coverage-2.7 on the command line.

Coverage has a number of commands which determine the action performed:

• run -- Run a Python program and collect execution data.
• report -- Report coverage results.
• html -- Produce annotated HTML listings with coverage results.
• xml -- Produce an XML report with coverage results.
• annotate -- Annotate source files with coverage results.
• erase -- Erase previously collected coverage data.
• combine -- Combine together a number of data files.
• debug -- Get diagnostic information.

Help is available with the help command, or with the --help switch on any other command:

$coverage help$ coverage help run
$coverage run --help  Version information for coverage.py can be displayed with coverage --version. Any command can use a configuration file by specifying it with the --rcfile=FILE command-line switch. Any option you can set on the command line can also be set in the configuration file. This can be a better way to control coverage.py since the configuration file can be checked into source control, and can provide options that other invocation techniques (like test runner plugins) may not offer. See :ref:config for more details. Execution You collect execution data by running your Python program with the run command: $ coverage run my_program.py arg1 arg2
blah blah ..your program's output.. blah blah


Your program runs just as if it had been invoked with the Python command line. Arguments after your file name are passed to your program as usual in sys.argv. Rather than providing a filename, you can use the -m switch and specify an importable module name instead, just as you can with the Python -m switch:

$coverage run -m packagename.modulename arg1 arg2 blah blah ..your program's output.. blah blah  If you want :ref:branch coverage <branch> measurement, use the --branch flag. Otherwise only statement coverage is measured. You can specify the code to measure with the --source, --include, and --omit switches. See :ref:Specifying source files <source_execution> for details of their interpretation. Remember to put options for run after "run", but before the program invocation: $ coverage run --source=dir1,dir2 my_program.py arg1 arg2


Combining data files

If you need to collect coverage data from different machines or processes, coverage can combine multiple files into one for reporting. Use the -p flag during execution to append distinguishing information to the .coverage data file name.

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  If the different machines run your code from different places in their file systems, coverage won't know how to combine the data. You can tell coverage how the different locations correlate with a [paths] section in your configuration file. See :ref:config_paths for details. If you are collecting and renaming your own data files, you'll need to name them properly for combine to find them. It looks for files named after the data file (defaulting to ".coverage", overridable with COVERAGE_FILE), with a dotted suffix. All such files in the current directory will be combined. Here are some examples of combinable data files: .coverage.machine1 .coverage.20120807T212300 .coverage.last_good_run.ok  Reporting Coverage provides a few styles of reporting, with the report, html, annotate, 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 filename patterns. They control which files to report on, and are described in more detail in :ref:source. 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. Coverage summary The simplest reporting is a textual summary produced with report: $ coverage report
Name                      Stmts   Miss  Cover
---------------------------------------------
my_program                   20      4    80%
my_module                    15      2    86%
my_other_module              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.

The -m flag also shows the line numbers of missing statements:

$coverage report -m Name Stmts Miss Cover Missing ------------------------------------------------------- my_program 20 4 80% 33-35, 39 my_module 15 2 86% 8, 12 my_other_module 56 6 89% 17-23 ------------------------------------------------------- TOTAL 91 12 87%  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                   20      4    80%   33-35, 39
my_other_module              56      6    89%   17-23
-------------------------------------------------------
TOTAL                        76     10    87%


Other common reporting options are described above in :ref:cmd_reporting.

HTML annotation

Coverage can annotate your source code for 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. The 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.

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 :ref:config_html 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 :ref:cmd_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. Text annotation 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  Other common reporting options are described above in :ref:cmd_reporting. XML reporting The xml command writes coverage data to a "coverage.xml" file in a format compatible with Cobertura. You can specify the name of the output file with the -o switch. Other common reporting options are described above in :ref:cmd_reporting. Diagnostics 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


Two types of information are available: sys to show system configuration, and data to show a summary of the collected coverage data.