diff options
| -rw-r--r-- | doc/cmd.rst | 124 | ||||
| -rw-r--r-- | doc/index.rst | 50 |
2 files changed, 157 insertions, 17 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 +---------- + diff --git a/doc/index.rst b/doc/index.rst index e3492d05..3d68da50 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,6 +2,9 @@ coverage.py
===========
+:history: 20090524T134300, brand new docs.
+:history: 20090524T134301, tweaked.
+
.. toctree::
:hidden:
@@ -9,6 +12,15 @@ coverage.py api
+.. FAQ
+.. Why do unexecutable lines show up as executed?
+.. Why do the bodies of fns show as executed, but the def lines do not?
+.. Change History
+.. Getting Help
+.. How it works
+.. .coverage file format
+.. Excluding lines
+
Coverage.py is a tool for measuring code coverage of Python programs. It monitors
your program, noting which parts of the code have been executed, then analyzes the
source to identify code that could have been executed but was not.
@@ -17,29 +29,35 @@ source to identify code that could have been executed but was not. Quick Start
-----------
-Install coverage.py from the cheeseshop.
+Getting started with coverage.py is easy:
+
+#. Install coverage.py from the `coverage page on the cheeseshop <http://pypi.python.org/pypi/coverage>`_.
-Run coverage.py to execute your program and gather data::
+#. Run coverage.py to execute your program and gather data::
- $ coverage -e -x my_program.py
- blah blah your program's output blah blah
+ $ coverage -e -x my_program.py arg1 arg2
+ blah blah ..your program's output.. blah blah
+
+ "-e -x" means erase coverage data from previous runs and execute a program.
-Run coverage.py to report on the results::
+#. Run coverage.py to report on the results::
+
+ $ coverage -r -m
+ 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%
- $ coverage -r -m
- Name Stmts Exec Cover Missing
- -------------------------------------------------------
- my_program 20 16 80% 33-35, 39
- my_other_module 56 50 89% 517-523
- -------------------------------------------------------
- TOTAL 76 66 87%
+ "-r -m" means show a summary report and include the missing line numbers.
-For a nicer presentation, run coverage.py to get annotated HTML listings
-detailing missed lines::
+#. For a nicer presentation, run coverage.py to get annotated HTML listings
+ detailing missed lines::
- coverage -b -d htmlcov
+ coverage -b -d htmlcov
-Then visit htmlcov/index.html in your browser.
+ Then visit htmlcov/index.html in your browser.
Using coverage.py
|