diff options
| -rw-r--r-- | CHANGES.txt | 4 | ||||
| -rw-r--r-- | doc/branch.rst | 8 | ||||
| -rw-r--r-- | doc/changes.rst | 2 | ||||
| -rw-r--r-- | doc/cmd.rst | 91 | ||||
| -rw-r--r-- | doc/config.rst | 13 | ||||
| -rw-r--r-- | doc/index.rst | 3 | ||||
| -rw-r--r-- | doc/source.rst | 76 | ||||
| -rw-r--r-- | doc/subprocess.rst | 10 |
8 files changed, 169 insertions, 38 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 2bff794f..5d200fcb 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -22,8 +22,8 @@ Version 3.4a1 never encountered at all, or if no data is collected. - The reporting commands (report, annotate, html, and xml) now have an - ``--include`` switch to restrict reporting to modules beginning with those - prefixes, similar to the existing ``--omit`` switch. Thanks, Zooko. + ``--include`` switch to restrict reporting to modules matching those file + patterns, similar to the existing ``--omit`` switch. Thanks, Zooko. - The run command now supports ``--include`` and ``--omit`` to control what modules it measures. This can speed execution and reduce the amount of data diff --git a/doc/branch.rst b/doc/branch.rst index 71681317..8f1583a1 100644 --- a/doc/branch.rst +++ b/doc/branch.rst @@ -10,10 +10,10 @@ Branch coverage measurement :linenothreshold: 5 -Coverage.py now supports branch coverage measurement. Where a line in your -program could jump to more than one next line, coverage.py tracks which of -those destinations are actually visited, and flags lines that haven't visited -all of their possible destinations. +In addition to the usual statement coverage, Coverage.py also supports branch +coverage measurement. Where a line in your program could jump to more than one +next line, coverage.py tracks which of those destinations are actually visited, +and flags lines that haven't visited all of their possible destinations. For example:: diff --git a/doc/changes.rst b/doc/changes.rst index 378e59c2..91af28be 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -1,4 +1,4 @@ -.. _change: +.. _changes: ==================================== Major change history for coverage.py diff --git a/doc/cmd.rst b/doc/cmd.rst index 08a966e4..c0eb85d0 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -13,8 +13,8 @@ Coverage command line usage .. highlight:: console -When you install coverage.py, a command-line script simply called coverage is -placed in your Python scripts directory. Coverage has a number of commands +When you install coverage.py, a command-line script simply called ``coverage`` +is placed in your Python scripts directory. Coverage has a number of commands which determine the action performed: * **run** -- Run a Python program and collect execution data. @@ -36,13 +36,20 @@ which determine the action performed: Help is available with ``coverage help``, or with the ``--help`` switch on any other command. -Version information for coverage.py can be displayed with ``--version``. +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. See :ref:`Configuration Files <config>` -for more details. +``--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:`Configuration Files <config>` for more +details. +.. _cmd_execution: + Execution --------- @@ -53,51 +60,68 @@ coverage command:: 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``. +Arguments after your file name are passed to your program as usual in +``sys.argv``. 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 +more details. + 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. +interpreter, for example, the standard library. 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 +If your coverage results seem to be overlooking code that you know has been 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 enabled by setting the environment variable COVERAGE_OPTIONS to ``--timid``. +If you are measuring coverage in a multi-process program, or across a number of +machines, you'll want the ``--parallel-mode`` switch to keep the data separate +during measurement. See :ref:`Combining data files <cmd_combining>` below. + + +.. _cmd_datafile: 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. +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 +.. _cmd_combining: 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. +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 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 **combine** command to combine them into one .coverage -data file. +data file:: + + $ coverage combine + +.. _cmd_reporting: Reporting --------- @@ -145,8 +169,14 @@ this will omit any modules in the django directory:: $ coverage report -m --omit django +.. TODO: modules are morfs. +.. TODO: omit is file patterns now +.. TODO Missing: --include +.. TODO Missing: -i +.. _cmd_html: + HTML annotation --------------- @@ -163,11 +193,17 @@ 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 specifies an output directory, and is required:: +The ``-d`` argument specifies an output directory, defaulting to "htmlcov":: + + $ coverage html -d coverage_html - $ coverage html -d covhtml +.. TODO: modules are morfs. +.. TODO Missing: -i +.. TODO Missing: --omit --include +.. _cmd_annotation: + Text annotation --------------- @@ -195,6 +231,12 @@ For example:: > else: > a = 2 +.. TODO: modules are morfs. +.. TODO Missing: -i +.. TODO Missing: --omit --include + + +.. _cmd_xml: XML reporting ------------- @@ -204,6 +246,13 @@ compatible with `Cobertura`_. .. _Cobertura: http://cobertura.sourceforge.net +.. TODO: modules are morfs. +.. TODO Missing: -i +.. TODO Missing: --omit --include +.. TODO Missing: --output-xml + + +.. _cmd_debug: Diagnostics ----------- diff --git a/doc/config.rst b/doc/config.rst index ada6d088..d3c38768 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -29,8 +29,8 @@ multiple lines. Boolean values can be specified as ``on``, ``off``, ``true``, ``false``, ``1``, or ``0`` and are case-insensitive. -Many sections and values correspond roughly to commands and options in the -command-line interface. +Many sections and values correspond roughly to commands and options in +the :ref:`command-line interface <cmd>`. Here's a sample configuration file:: @@ -84,6 +84,7 @@ many processes. ``timid`` (boolean, default False): use a simpler but slower trace method. Try this if you get seemingly impossible results. +.. TODO missing: source, include, omit. [report] -------- @@ -102,11 +103,14 @@ found. ``omit`` (multi-string): a list of file prefixes. If a source file begins with one of these prefixes, it will be omitted from the report. +.. TODO: omit is file patterns now +.. TODO missing: include [html] ------ -Values particular to HTML reporting. +Values particular to HTML reporting. The values in the ``[report]`` section +also apply to HTML output. ``directory`` (string, default "htmlcov"): where to write the HTML report files. @@ -114,6 +118,7 @@ Values particular to HTML reporting. [xml] ----- -Values particular to XML reporting. +Values particular to XML reporting. The values in the ``[report]`` section +also apply to XML output. ``output`` (string, default "coverage.xml"): where to write the XML report. diff --git a/doc/index.rst b/doc/index.rst index 6ce3e827..7d608160 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -91,7 +91,7 @@ History Coverage.py was originally written by `Gareth Rees`_. Since 2004, `Ned Batchelder`_ has extended and maintained it with the help of -`many others`_. +`many others`_. The :ref:`change history <changes>` has all the details. .. _Gareth Rees: http://garethrees.org/ .. _Ned Batchelder: http://nedbatchelder.com @@ -107,6 +107,7 @@ More information cmd config api + source excluding branch subprocess diff --git a/doc/source.rst b/doc/source.rst new file mode 100644 index 00000000..edfc2fcf --- /dev/null +++ b/doc/source.rst @@ -0,0 +1,76 @@ +.. _source: + +======================= +Specifying source files +======================= + +:history: 20100725T172000, new in 3.4 + + +When coverage.py is running your program and measuring its execution, it needs +to know what code to measure and what code not to. Measurement imposes a speed +penalty, and the collected data must be stored in memory and then on disk. +More importantly, when reviewing your coverage reports, you don't want to be +distracted with modules that aren't your concern. + +Coverage.py has a number of ways you can focus it in on the code you care +about. + + +.. _source_execution: + +Execution +--------- + +When running your code, the ``coverage run`` command will by default measure +all code, unless it is part of the Python standard library. + +You can specify source to measure with the ``--source`` command-line switch, +or the ``[run] source`` configuration value. The value is a list of directories +or package names. If specified, only source inside these directories or +packages will be measured. + +You can further fine-tune coverage.py's attention with the ``--include`` and +``--omit`` switches (or ``[run] include`` and ``[run] omit`` configuration +values). ``--include`` is a list of filename patterns. If specified, only files +matching those patterns will be measured. ``--omit`` is also a list of filename +patterns, specifying files not to measure. If both ``include`` and ``omit`` +are specified, first the set of files is reduced to only those that match the +include patterns, then any files that match the omit pattern are removed from +the set. + +The ``include`` and ``omit`` filename patterns follow typical shell syntax: +``*`` matches any number of characters and ``?`` matches a single character. +The full semantics are specified in the `fnmatch docs`_. + +.. _fnmatch docs: http://docs.python.org/library/fnmatch.html + +The ``source``, ``include``, and ``omit`` values all work together to determine +the source that will be measured. + + +.. _source_reporting: + +Reporting +--------- + +Once your program is measured, you can specify the source files you want +reported. Usually you want to see all the code that was measured, but if you +are measuring a large project, you may want to get reports for just certain +parts. + +The report commands (``report``, ``html``, ``annotate``, and ``xml``) all take +optional ``modules`` arguments, and ``--include`` and ``--omit`` switches. The +``modules`` arguments specify particular modules to report on. The ``include`` +and ``omit`` values are lists of filename patterns, just as with the ``run`` +command. + +Remember that the reporting commands can only report on the data that has been +collected, so the data you're looking for may not be in the data available for +reporting. + +Note that these are ways of specifying files to measure. You can also exclude +individual source lines. See :ref:`Excluding code from coverage <excluding>` +for details. + + diff --git a/doc/subprocess.rst b/doc/subprocess.rst index d976f692..81756810 100644 --- a/doc/subprocess.rst +++ b/doc/subprocess.rst @@ -8,15 +8,15 @@ Measuring subprocesses Complex test suites may spawn subprocesses to run tests, either to run them in -parallel, or because subprocess behavior is an important part of the code under -test. Measuring coverage in those subprocesses can be tricky because you have -to modify the code spawning the process to invoke coverage.py. +parallel, or because subprocess behavior is an important part of the system +under test. Measuring coverage in those subprocesses can be tricky because you +have to modify the code spawning the process to invoke coverage.py. There's an easier way to do it: coverage.py includes a function, :func:`coverage.process_startup` designed to be invoked when Python starts. It examines the ``COVERAGE_PROCESS_START`` environment variable, and if it is set, -begins coverage measurement. Its value will be used as the name of the -:ref:`configuration file <config>` to use. +begins coverage measurement. The environment variable's value will be used as +the name of the :ref:`configuration file <config>` to use. When using this technique, be sure to set the parallel option to true so that multiple coverage.py runs will each write their data to a distinct file. |