.. ===================================================================
.. Biskit, a toolkit for the manipulation of macromolecular structures
.. Copyright (C) 2004-2005 Raik Gruenberg & Johan Leckner
..
.. This program is free software; you can redistribute it and/or
.. modify it under the terms of the GNU General Public License as
.. published by the Free Software Foundation; either version 2 of the
.. License, or any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.. General Public License for more details.
..
.. You find a copy of the GNU General Public License in the file
.. license.txt along with this program; if not, write to the Free
.. Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
..
..
.. last $Author$
.. last $Date$
.. $Revision$
.. ===================================================================

.. Testing your Biskit setup
.. *************************

- Each *Biskit* module comes with its own test class (derrived from
  Biskit.test.BiskitTest).

- All the input data needed to run the tests is checked into the 
  project and can be found in the folder *~biskit/test*. 
  
- The tests are independent of each other and there is no 
  need to execute them in a specific order. 

- Many of the tests write an output to disc. The directory used for the 
  output is the folder given by *tempfile.tempdir*, normally */tmp*. 

- TAGS classify tests into categories that can be included or excluded
  from a test run, currently these are: LONG, OLD, EXE, PVM


Testing a single module:
========================
To test a single module just execute the module, for example::

  cd biskit/Biskit
  python -i PDBModel.py

...will run the PDBModel test case and release you into an interactive
interpreter to inspect the result.


Testing the full installation: 
==============================

Testing of the full installation is facilitated by a script
*~biskit/Biskit/test.py* (in fact, test.py also is the module that
defines the whole Biskit testing infrastructure ). This script accepts
a few options. The most useful option may be -e to exclude tests by
their tags and -p which allows you to narrow down testing to a Biskit
sub-package

To get some help from the script, call it without arguments::

  python test.py

Example 1,
  test everything::

    python test.py -v 2

(give any default option to prevent the printing of the help
screen). After having typed that, going for lunch or a walk may be a
good idea, especially if your docking and homology modeling
installation is complete.

Example 2,
  only test core Biskit without external programs or pvm-dependent code::

    python test.py -p Biskit -e exe pvm

Example 3,
  only test docking and homology modeling external programs::

    python test.py -p Biskit.Mod Biskit.Dock -i exe


Writing your own test:
======================

Biskit.test automatically collects all BiskitTest-derrived test cases
from all Biskit modules. The documentation in Biskit.test contains a
ready-made template for your own test case and all the necessary (or
maybe unnecessary) instructions.

