diff options
Diffstat (limited to 'doc/cmd.rst')
| -rw-r--r-- | doc/cmd.rst | 124 |
1 files changed, 123 insertions, 1 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 8eb63ad7..5b4b7a3e 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -4,4 +4,126 @@ Coverage Command Line usage =========================== -Using the command line is easy! +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 +---------- + |