=========
TestGears
=========

TestGears provides automatic discovery of unittest.TestCases and the
ability to run tests that are written as simple functions. It
generates a standard unittest.TestSuite for use with any of the
standard frontends, and provides a distutils command to run tests
with zero configuration.

Simplicity is the name of the game. TestGears is easy to install
and makes it easy to write and run tests within the unittest framework. 
If you need to run tests remotely or directly from a Subversion
repository, you should look at `py.test`_. If you want multithreaded
tests or HTML output, check out `testoob`_.

TestGears was inspired by the ease of writing tests with `py.test`_
and Phillip Eby's assertion that `extending unittest is better than
creating new frameworks`__.

.. _testoob: http://testoob.sourceforge.net/
.. _py.test: http://codespeak.net/py/current/doc/test.html
__ http://dirtsimple.org/2005/08/ruby-gems-python-eggs-and-beauty-of.html

Getting TestGears
-----------------

The current version of TestGears is 0.2. The easiest way to get TestGears
is via Easy Install. If you do not yet have Easy Install, you can
get it by downloading and running ez_setup.py:

http://peak.telecommunity.com/dist/ez_setup.py

Once you have it, you can use Easy Install to install TestGears::

    python -m easy_install -fhttp://www.turbogears.org/testgears/ TestGears

This command will install the Python Egg:

http://www.turbogears.org/download/eggs/TestGears-0.2-py2.4.egg

If you prefer a standard Python source distribution, you can get that
here:

http://www.turbogears.org/download/eggs/TestGears-0.2.tar.gz

Documentation
-------------

This file is the primary user documentation. Additionally, you
can find the Pudge-generated module and source docs by going
to the `module index`__.

__ module-index.html

Usage
-----

The easiest usage is via a setuptools setup script. (Note that if 
you're already using distutils, you can just change 
"from distutils.core import setup" to 
"from setuptools import setup".)::

    from setuptools import setup
    setup(name='foo',
          version='1.0',
          packages=['foo'],
          )

From the command line, you run::

    python setup.py testgears

TestGears will scan the "foo" package for test classes. Note that, at
present, only the first package listed is scanned for tests.

If you wish to use TestGears with some other test runner, you can 
create a traditional test suite like this::

    from testgears import collector
    suite = collector.Collector("foo")

How TestGears Finds Tests
-------------------------

TestGears looks through the files and directories within the 
provided package to find Python files that **start with "test_"**.

Within those files, it looks for:

1. Subclasses of unittest.TestCase that start with "test" 
   (case insensitive).
2. Functions that start with "test" (case insensitive).

unittest.TestCase tests are run in the traditional manner. This 
means that setUp/tearDown methods are called and the tests are 
run in alphabetical order.

Functions are run in the order in which they appear in the file.

Setup/Teardown Functions
------------------------

For standard unittest.TestCase instances, the normal setUp and
tearDown methods are called.

Additionally, TestGears looks for functions called setup_module
and teardown_module in your test modules. These will be called
before and after, respectively, any tests in your module.
These functions are called with the module itself as a parameter.

Regular Expression Matching
---------------------------
The collector allows you to specify a "regex" option to limit 
the tests that are run to the ones that match your expression.

If the regex matches on a filename, all of the tests in that file 
are run. If it doesn't match the filename, the names of the test 
functions or unittest.TestCases are compared with the expression. 
Only those that match will be run. For example, imagine the 
following test file::

    test_foo.py:
        class TestBar(unittest.TestCase):
            def test_glorp(self):
                pass
            
            def test_grond(self):
                pass
        
        def test_baz():
            pass

Here is how matching would work for some expressions:

* ".*foo" will run all of the tests
* ".*Bar" will run all of the tests in TestBar
* ".*glorp" will **not** run any tests, because TestGears does not
   manage the tests inside of a TestCase
* ".*baz" will only run the test_baz function

Subversion Access
-----------------
TestGears does not yet have a public repository. It will
in the future.

Contact
-------
If there is interest in extending or adding to TestGears, I'll create
a mailing list. In the meantime, you can send any questions,
suggestions or problems to Kevin Dangoor at 
dangoor+testgears -at- gmail.com.