Testing PyUtilib
================

This directory is used to test the PyUtilib 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 PyUtilib 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 

 . Python 2.5 or newer
 . 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
------------

PyUtilib 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. pyutilib/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 PyUtilib is the specification of the Python
    system path.  The following lines are commonly used at the head of
    PyUtilib 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 PyUtilib 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.


