Testing FAST
=============

The following subdirectories are used to test the FAST libraries
with strictly Python capabilities.  That is, these do not rely on
external solvers/libraries.


Running Tests
-------------

You can run tests by typing

  ./runtests

or you can run tests for a particular FAST package by typing

  ./runtests <pkg-name>

This command requires the Python 'nose' package.  See http://www.somethingaboutorange.com/mrl/projects/nose/ for details on this package.

This command also requires the use of Python 2.5 or newer.  This command also
requires the Python coverage module to generate code coverage statistics. 
Without this module, an error message will be generated, but that error
can be ignored.

Advanced features of this command can be viewed by typing

  ./runtests --help


Adding Tests
------------

FAST tests employ unit tests.  These tests execute the Python standard unittest framework, and the nose package is used for test discovery and test execution.

Adding tests can be described in three steps:

* Pick test directory

  Nose looks recursively looks for tests in directories that contain a
    __init__.py file.  If you are adding tests to an existing package, you
    can simply put the test file in the unit test directory for that
    package (e.g. coopr/test/util/unit).  If you need to create a new
    test directory, that directory simply needs an empty __init__.py file.

* Setup unittest file

  Python's unittest framework is well-documented (e.g. see 
    http://docs.python.org/lib/module-unittest.html).  The main issue for
    setting up unittest files in FAST is the specification of the Python
    system path.  The following lines are commonly used at the head of
    FAST unittest files:

    import os
    import sys
    from os.path import abspath, dirname
    sys.path.insert(0, dirname(dirname(abspath(__file__)))+"/../..")

  With this configuration, Python can import FAST without changing the
  PYTHONPATH environment varible.

* Creating tests

  The Python unit testing framework is a Python language version of JUnit, 
    which is the de factor unit testing framework for Java.  Unit tests are
    setup by deriving a class from the unittest.TestCase class, and then
    creating methods with a name staring with 'test_'.  These methods can
    apply a variety of test conditions to evaluate the test correctness,
    and to report that result to the testing framework.


