diff options
| -rw-r--r-- | CHANGES.txt | 4 | ||||
| -rw-r--r-- | doc/cmd.rst | 105 | ||||
| -rw-r--r-- | doc/excluding.rst | 2 | ||||
| -rw-r--r-- | doc/faq.rst | 9 | ||||
| -rw-r--r-- | doc/index.rst | 15 |
5 files changed, 74 insertions, 61 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index b29c1f0..adc4f09 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -5,6 +5,10 @@ Change history for Coverage.py Next version
------------
+- Coverage.py has a new command line syntax with subcommands. This expands the
+ possibilities for adding features and options in the future. The old syntax
+ is still supported.
+
- Added the --timid option to enable a simpler slower trace function that works
for DecoratorTools (including TurboGears) projects.
diff --git a/doc/cmd.rst b/doc/cmd.rst index ae7282f..3a3451a 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -6,84 +6,87 @@ Coverage command line usage :history: 20090524T134300, brand new docs. :history: 20090613T164000, final touches for 3.0 +:history: 20090913T084400, new command line syntax .. highlight:: console 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: +your Python scripts directory. Coverage has a number of commands which +determine the action performed: -* -e Erase previously collected coverage data. +* **run** -- Run a Python program and collect execution data. -* -x Execute a Python program and collect execution data. +* **report** -- Report coverage results. -* -c Combine together a number of data files. +* **html** -- Produce annotated HTML listings with coverage results. -* -r Report coverage results. +* **erase** -- Erase previously collected coverage data. -* -a Annotate source files with coverage results. +* **combine** -- Combine together a number of data files. -* -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 +* **annotate** -- Annotate source files with coverage results. Execution --------- -Coverage collects data by running your Python program with -x:: +You collect execution data by running your Python program with the **run** +coverage command:: - $ coverage -x my_program.py arg1 arg2 + $ 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 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. +If you want to measure that code as well as your own, add the ``-L`` flag. If your coverage results seems to be overlooking code that you know has been -executed, try running coverage again with the --timid flag. This uses a simpler +executed, try running coverage again with the ``--timid`` flag. This uses a simpler but slower trace method. Projects that use DecoratorTools, including TurboGears, -will need to use --timid to get correct results. This option can also be set -with the environment variable COVERAGE_OPTIONS set to '--timid'. +will need to use ``--timid`` to get correct results. This option can also be set +with the environment variable COVERAGE_OPTIONS set to ``--timid``. + + + +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. By default, +each run of your program starts with an empty data set. If you need to run your +program multiple times to get complete data (for example, because you need to +supply disjoint options), you can accumulate data across runs with the ``-a`` +flag on the **run** command. + +To erase the collected data, use the **erase** command:: + + $ coverage erase + Combining data files -------------------- If you need to collect coverage data from different machines, coverage can -combine multiple files into one for reporting. Use the -p flag during execution -to append a machine name and process id to the .coverage data file name. +combine multiple files into one for reporting. Use the ``-p`` flag during +execution to 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 +directory, and use the **combine** command to combine them into one .coverage +data file. Reporting --------- Coverage provides a few styles of reporting. The simplest is a textual summary -produced with -r:: +produced with **report**:: - $ coverage -r + $ coverage report Name Stmts Exec Cover --------------------------------------------- my_program 20 16 80% @@ -96,9 +99,9 @@ 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:: +The ``-m`` flag also shows the line numbers of missing statements:: - $ coverage -r -m + $ coverage report -m Name Stmts Exec Cover Missing ------------------------------------------------------- my_program 20 16 80% 33-35, 39 @@ -110,7 +113,7 @@ The -m flag also shows the line numbers of missing statements:: You can restrict the report to only certain files by naming them on the command line:: - $ coverage -r -m my_program.py my_other_module.py + $ coverage report -m my_program.py my_other_module.py Name Stmts Exec Cover Missing ------------------------------------------------------- my_program 20 16 80% 33-35, 39 @@ -118,10 +121,10 @@ command line:: ------------------------------------------------------- TOTAL 76 66 87% -The -o flag omits files that begin with specified prefixes. For example, this +The ``-o`` flag omits files that begin with specified prefixes. For example, this will omit any modules in the django directory:: - $ coverage -r -m -o django + $ coverage report -m -o django @@ -129,9 +132,9 @@ HTML annotation --------------- Coverage can annotate your source code 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. +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 </code/coverage/sample_html/index.html>`_. @@ -139,18 +142,18 @@ 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. -The -d argument to specify an output directory is required:: +The ``-d`` argument to specify an output directory is required:: - $ coverage -b -d covhtml + $ coverage html -d covhtml Text annotation --------------- -The -a flag 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. +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:: diff --git a/doc/excluding.rst b/doc/excluding.rst index d336813..0dfee51 100644 --- a/doc/excluding.rst +++ b/doc/excluding.rst @@ -20,7 +20,7 @@ the "if debug" clause is excluded from reporting:: msg = "blah blah" log_message(msg, a) b = my_function2() - + Any line with a comment of "pragma: no cover" is excluded. If that line introduces a clause, for example, an if clause, or a function or class definition, then the entire clause is also excluded. Here the __repr__ diff --git a/doc/faq.rst b/doc/faq.rst index d1b4160..385f1fe 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -9,6 +9,7 @@ FAQ and other help Frequently asked questions -------------------------- + **Q: Why do unexecutable lines show up as executed?** Usually this is because you've updated your code and run coverage on it @@ -16,8 +17,10 @@ again without erasing the old data. Coverage records line numbers executed, so the old data may have recorded a line number which has since moved, causing coverage to claim a line has been executed which cannot be. -Use the -e switch on the command line to erase all data before starting the next -run. +If you are using the ``-x`` command line action, it doesn't erase first by +default. Switch to the ``coverage run`` command, or use the ``-e`` switch to +erase all data before starting the next run. + **Q: Why do the bodies of functions (or classes) show as executed, but the def lines do not?** @@ -32,10 +35,12 @@ to run your program with coverage, then your entire program will be monitored. If you are using the :ref:`API <api>`, you need to call coverage.start() before importing the modules that define your functions. + **Q: Does coverage work on Python 3.x?** Not yet, but that's next on my list. + **Q: Isn't coverage testing the best thing ever?** It's good, but `it isn't perfect diff --git a/doc/index.rst b/doc/index.rst index a300678..884a255 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,6 +6,7 @@ coverage.py :history: 20090613T164000, final touches for 3.0
:history: 20090618T195900, minor tweaks
:history: 20090707T205200, changes for 3.0.1
+:history: 20090913T084400, new command line syntax
Coverage.py is a tool for measuring code coverage of Python programs. It
@@ -30,18 +31,18 @@ Getting started is easy: or by using "easy_install coverage". You may need to install the
python-dev support files, for example with "apt-get install python-dev".
-#. Run coverage to execute your program and gather data:
+#. Use ``coverage run`` to execute your program and gather data:
.. code-block:: console
- $ coverage -e -x my_program.py arg1 arg2
+ $ coverage run my_program.py arg1 arg2
blah blah ..your program's output.. blah blah
-#. Run coverage to report on the results:
+#. Use ``coverage report`` to report on the results:
.. code-block:: console
- $ coverage -r -m
+ $ coverage report -m
Name Stmts Exec Cover Missing
-------------------------------------------------------
my_program 20 16 80% 33-35, 39
@@ -49,12 +50,12 @@ Getting started is easy: -------------------------------------------------------
TOTAL 76 66 87%
-#. For a nicer presentation, run coverage to get annotated HTML listings
- detailing missed lines:
+#. For a nicer presentation, use ``coverage html`` to get annotated HTML
+ listings detailing missed lines:
.. code-block:: console
- $ coverage -b -i -d htmlcov
+ $ coverage html -i -d htmlcov
Then visit htmlcov/index.html in your browser, to see a
`report like this </code/coverage/sample_html/index.html>`_.
|