Reporters
*********







A reporter will present some information found in the database of
execution results. A reporter may directly output a file (usually an image) or a
report object that will be formatted using a formatters_. There are two kinds of
reporters: simple reporters which create their content from a single tests
execution result (i.e. for a daily result), whereas evolution reporters build
report by analysing changes between two or more tests execution results.

Most reporters support the following options :

+-----------------+-----+-----------------------------------------------------+
|     name        | req |   description                                       |
+=================+=====+=====================================================+
| link_to         | no  | link to another report internaly                    |
+-----------------+-----+-----------------------------------------------------+
| filter          | no  | comma separated list of test names to consider      |
|                 |     | (default to all)                                    |
+-----------------+-----+-----------------------------------------------------+
| title           | no  | report title                                        |
+-----------------+-----+-----------------------------------------------------+
| top_links       | no  | link to other reports on the report's top           |
+-----------------+-----+-----------------------------------------------------+
| summary         | no  | summary level (0 disable it, default to 2)          |
+-----------------+-----+-----------------------------------------------------+
| treshold        | no  | log treshold to include messages (default to ERROR) |
|                 |     | possible values are : INFO, WARNING, ERROR          |
+-----------------+-----+-----------------------------------------------------+

APyCot comes with the following reporters. If you don't find the feature
you're  looking for, you may still write your own reporter, and contribute
it ;). The best way to do so for the moment is to look at the existant ones...
Some reporters depends on a third-party program (usually a Python package or
an external command), so they may be not available according to your system
setup. 




Simple reporters
````````````````
A simple reporter acts on a single tests execution result. 

minimal_report
~~~~~~~~~~~~~~
:output: report object requiring a formatter
:description:
  This report display most information but not log messages. Each test has its
  own section, with checks in subsections. 
:sample: textminimal_, htmlminimal_

synthetized_report
~~~~~~~~~~~~~~~~~~
:output: report object requiring a formatter
:description:
  A short table report with tests as rows and checks as columns, displaying 
  the status matrix.
:sample: textcolumn_, htmlcolumn_

detailed_report
~~~~~~~~~~~~~~~
:output: report object requiring a formatter
:description:
  A full report including log messages, raw values for each check of each test
  in their respective subsection / section.
:sample: textdetailed_, htmldetailed_

multi_files_detailed_report
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:output: a set of report objects requiring a formatter
:description:
  The same content as the detailed_report_ but with each test data in a
  separated file.
:sample: htmlmultifiles_

contest_report
~~~~~~~~~~~~~~
:output: report object requiring a formatter
:description:
  Ths report display information extracted by the contest *decorator* in an
  ordered table, using selected field as columns, and tests as row in an ordered
  manner.
  **You must use the contest decorator to get this report.**
:sample: htmlcontest_


Evolution reporters
```````````````````

An evolution reporter acts on a set of tests execution results. Below are some
usual options found on evolution reporters :

+-------------+-----+---------------------------------------------------------+
|    name     | req |   description                                           |
+=============+=====+=========================================================+
| interval    | no  | number of time unit (day or hour depending of the mode  |
|             |     | to take in consideration (default to 1)                 |
+-------------+-----+---------------------------------------------------------+
| columns     | no  | field to take accounts (default to all)                 |
+-------------+-----+---------------------------------------------------------+

An evolution reporter takes the latest test execution date or the one given to
runreports using the --date option as reference, and consider test results
<interval> time unit until this date.

status_evolution_report
~~~~~~~~~~~~~~~~~~~~~~~
:output: report object requiring a formatter

  Display the evolution of the total number of checks, with the number of
  succeed, failed, error checks (and optionaly other checks'status) in a table
  with date as row.

:status: textstatus_


status_evolution_graph
~~~~~~~~~~~~~~~~~~~~~~
:output: image file
:depends on: biggles_
:description:
  The same content as the status_evolution_report report but in graphical form.

:sample: statusevolution_

+-------------+-----+---------------------------------------------------------+
|    name     | req |   description                                           |
+=============+=====+=========================================================+
| graph_type  | no  | default to line                                         |
+-------------+-----+---------------------------------------------------------+

activity_evolution_graph
~~~~~~~~~~~~~~~~~~~~~~~~
:description:
  status evolution report as an image fil


test_activity_report
~~~~~~~~~~~~~~~~~~~~
:output: image file
:require:  activity decorator on
:description:

  test activity report: include test status change and vcs activity

.. _textcolumn: samples/index.txt
.. _textminimal: samples/text_minimal_report.txt
.. _textdetailed: samples/text_detailed_report.txt
.. _htmlcolumn: samples/index.html
.. _htmlminimal: samples/html_minimal_report.html
.. _htmldetailed: samples/html_detailed_report.html
.. _htmlmultifiles: samples/apycot.html
.. _htmlcontest: samples/contest.html
.. _textstatus: samples/evolution_report.txt
.. _statusevolution: samples/evolution_report.png

.. _biggles: http://biggles.sourceforge.net
.. _viewcvs: http://viewcvs.sourceforge.net
