-------------------------------------------------------------------------------

                      EDOS meta test runner

-------------------------------------------------------------------------------

François Déchelle    <fdechelle@mandriva.com>


1- Content
----------

This module contains the EDOS meta test runner.

The EDOS meta test runner runs tests described by an XML file and
reports test results using report 'plug-ins'. Several report
'plug-ins' are available, using for instance HTTP POST requests.


2- Prerequisites
----------------

You need the following packages:
python
python-pyxml
python-rpm (if running on a RPM based distribution)
python-cherrypy (only for the debug server)


3- Running
----------

To run the test runner, you must first make sure that the Python
package 'edostestrunner' can be found by the Python interpreter.

If you have installed the EDOS test runner in a standard
directory, for instance by using a package (RPM or Debian) version of
the EDOS test runner, setting PYTHONPATH is not mandatory and you can
skip paragraphe 3.1.

3.1- Setting PYTHONPATH
-----------------------

If you have installed the package in a non-standard directory, you
must set the PYTHONPATH environment variable. The value to give to
PYTHONPATH is different if you are using directly the source tree or
if you have installed the EDOS test runner.

3.1.1- Running from the source tree
-----------------------------------

Setting PYTHONPATH can be done by:
export PYTHONPATH=PATH_TO_SOURCE_TREE

For instance:
export PYTHONPATH=/var/tmp/edostestrunner-1.0.2alpha

if you have extracted edos-testrunner-1.0.2alpha.tar.gz in directory /var/tmp

3.1.2- Running after installing test runner
-------------------------------------------

See paragraph 4 for installation instructions.

Setting PYTHONPATH can be done by:
export PYTHONPATH=PREFIX/lib/python2.4/site-packages

where PREFIX is the prefix directory that you have specified in installation.

For instance, if you have installed test runner with:
python setup.py install --prefix=$HOME/projects/EDOS/install

then you must set PYTHONPATH with:
export PYTHONPATH=$HOME/projects/EDOS/install/lib/python2.4/site-packages

3.2 Running test runner
-----------------------

After setting PYTHONPATH, you can run the test runner with:
edos-runtest --file=<<test XML file>>

An example test XML file test1.xml is located in subdirectory tests/
of the source tree.

For more help on edos-testrun options:
edos-runtest --help


4- Installation
---------------

This module uses Python distutils tools.

To install it under directory PREFIX:
python setup.py install --prefix=PREFIX <<other install options>>

To get full list of install options:
python setup.py install --help



5- Configuration
----------------

The test runner can use a configuration file, that can either
- reside in standard locations (namely
/etc/edos-testrunner/testrunner.cfg or $HOME/.edos-testrunner.cfg
where $HOME is the home directory of the user calling the script)
- be passed on command line with option -c FILE or --config-file=FILE

A template configuration file edos-testrunner.cfg.sample is given in
subdirectory config/ of source directory.

Example of configuration file:
==================================================
[Testing]
# Base directory where tests will be run
#localstatedir=/var/lib
#testdir=%(localstatedir)s/edos-testrunner/test

[Reporting]
# The list, separated by ',', of test reporters
reporter=stdout1,xwiki1
#reporter=StdoutTestReporter

[stdout1]
class=StdoutTestReporter

[xwiki1]
class=XwikiTestReporter
# Hostname of the reporting service
server=mandriva.edos-project.org
#server=stalker
# Port used by the reporting service
port=80
#port=8080

[Identification]
# Registered username for the reporting service
username=noname
==================================================



6- Debug reporting service
--------------------------

For debugging, a reporting server can be found in:
tests/debugserver.py

To run it:
python debugserver.py

This server uses the cherrypy framework which must be therefore be
installed.

