Concepts
--------







This section defines the vocabulary used and presents the global architecture of
APyCoT.


Vocabulary
**********

- A **repository** is a usually version controled source database, like 
  SVN or Hg.

- A **package** is a generic term for some files related together as a
  project in a source repository.

- A **preprocessor** allow a specific construction / installation step required to
  build a test environment.

- A **check** is a single functional test which may be applied to test
  a package. A **checker** is the object applying this functional
  test.

- A **test suite** (or shortly a **test**) is defined in a tests
  configuration file. A test defines:

  - the repository of the package to test,
  - the path of the package in the repository,
  - optionaly a revision tag,
  - the list of checkers to apply,
  - checkers specific options,
  - a list of dependencies which have to be installed in the test
    environment.

- The **result database** is the set of gathered results from
  the daily execution of tests (currently a set of xml files).

- A **report** is created by the following components:

  - a **decorator** that may be used to add some information to the tests data,
    such as checkins log messages,

  - a **reporter** which create the content of the report from data collected
    during tests execution,

  - a **formatter** is then used to transform the report object to a
    particular format (plain text, html...),

  - a **transport** is finally used to write the report on the file system,
    send it by mail and so on.


Global architecture
*******************

The following diagram describes the different parts of this testing
automation framework.

.. image:: global_archi.png

Components interacting are :

- *runtest*, which is responsible for a single test suite
  execution. A test will be run in a dedicated environment, created
  by extracting data and optionaly doing some preprocessing on it. It
  outputs the test execution results on stdout using a user friendly
  format or an easily parsable one, dedicated to communicate with
  *runtests*.

- *runtests* coordinate all the tests execution. It will spawn
  simultaneously a predefined number of tests by launching the
  *runtest* command and parses their outputs back in order to write
  them to a result database.

- *runreports* extract data from the result database and create
   different reports from that data.

You will have to write two configuration files to describe both your
needs and your environment:

1. a tests definition for *runtests* and *runtest*. This file describes your
   packages, how to fetch them, which checks should be applied to each of
   them and so on,

2. a reports defintion for *runreports*. This file describesxs reports that
   should be generated from the gathered data.
