1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
.. _cmd:
===========================
Coverage Command Line usage
===========================
When you install coverage, a command-line script called coverage is placed in
the Python scripts directory. Coverage performs a number of actions, determined
by the flags on the command line:
* -e Erase previously collected coverage data.
* -x Execute a Python program and collect execution data.
* -c Combine together a number of data files.
* -r Report coverage results.
* -a Annotate source files with coverage results.
* -b Produce annotated HTML listings with coverage results.
Some of these can be combined: for example, "-e -x" is the simple way to run a
program without carrying over previous data.
Data File
---------
Coverage collects execution data in a file called ".coverage". If need be, you can
set a new file name with the COVERAGE_FILE environment variable. Data accumulates
from run to run, so that you can collect a complete data set of which parts of
your code are executed.
To erase the collected data, use the "-e" command-line switch::
$ coverage -e
Execution
---------
Coverage collects data by running your Python program with -x::
$ coverage -x 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 in sys.argv.
By default, coverage does not measure code installed with the Python interpreter.
If you want to measure that code as well as your own, add the -L flag.
Combining Data Files
--------------------
For some applications, your code will run on a number of different machines.
To make it easier to collect together the .coverage data files from these runs,
the -p flag will append a machine name and process id 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 -c flag to combine them into one .coverage data file::
$ coverage -c
Reporting
---------
Coverage provides a few styles of reporting. The simplest is a textual summary
produced with -r::
$ coverage -r
Name Stmts Exec Cover
---------------------------------------------
my_program 20 16 80%
my_module 15 13 86%
my_other_module 56 50 89%
---------------------------------------------
TOTAL 91 79 87%
For each module executed, the report shows the count of executable statements,
the number of those statements executed, and the resulting coverage, expressed
as a percentage.
The -m flag also shows the line numbers of missing statements::
$ coverage -r -m
Name Stmts Exec Cover Missing
-------------------------------------------------------
my_program 20 16 80% 33-35, 39
my_module 15 13 86% 8, 12
my_other_module 56 50 89% 17-23
-------------------------------------------------------
TOTAL 91 79 87%
You can restrict the report to files you are interested in by naming them on the
command line::
$ coverage -r -m my_program.py my_other_module.py
Name Stmts Exec Cover Missing
-------------------------------------------------------
my_program 20 16 80% 33-35, 39
my_other_module 56 50 89% 17-23
-------------------------------------------------------
TOTAL 76 66 87%
You can use the -o flag to omit files that begin with specified prefixes.
For example, this will skip reporting on any modules in the django directory::
$ coverage -r -m -o django
HTML Annotation
---------------
Coverage can show you your source code, annotated for which lines were executed,
and which were not. The -b flag creates an HTML report similar to the -r
summary, but as an HTML file. Each module name links to the source file
decorated to show the status of each line.
Annotation
----------
|
