What is the Statement Coverage Reporter
---------------------------------------

Our statement coverage reporter relies on the coverage module originally written 
by Gareth Rees and improved by Ned Batchelder.

It can be installed under Debian and Debian derived systems by entering at the
command line::

    apt-get install python-coverage

or by using easy_install::

    easy_install coverage

<awaiting instructions for other operating systems>

How to Use It
-------------

It's a trial reporter, it *reports* statement coverage information after the
output of the unit tests.
First you need to make sure that is it part of your PYTHONPATH.
This is done by adding elisa-core to your PYTHONPATH.
Then you call `trial` like so::

    trial --reporter coverage <module>

for examples:

from the elisa-core directory (assuming PYTHONPATH is set correctly)::

    trial --reporter coverage elisa.core

or from elisa-plugins::

    trial --reporter coverage elisa.plugins.http_client

Which gives you a report that looks like this::

    Coverage Report:
    Name                                    Stmts   Exec  Cover   Missing
    ---------------------------------------------------------------------
    elisa/plugins/http_client/__init__          0      0   100%   
    elisa/plugins/http_client/http_client     186    182    97%   96, 215, 281-283
    ---------------------------------------------------------------------
    TOTAL                                     186    182    97%

Some Questions and Answers About This Tool
------------------------------------------

Q: How is it determined which files are reported about?

A: A list of every directory where a test case was executed (minus "tests", of
course) is collected, this is matched against the total list of files we have
coverage information about.  The report is based on this intersection.

Q: I want to see which lines were executed and which lines weren't in my
file(s).

A: They can be found in the directory tree under <filename>,cover.

Q: How is this tool different from using `--coverage`?

A: `--coverage` doesn't provide a summary report and coverage information about
*all* files executed can be found in `_trial_temp/coverage/` from the directory
where `trial` is called.
