[Grok-dev] Easier test setup with new grok.testing

[Uli Fouquet]

Hi there,

I just merged my testsetup extension into the branch, because I am lazy,
my memory is like a sieve and I didn't want to remember all the dirty
details of test setups any more when starting a new grok project. Hope,
nothing will break.

To make use of this extension in your grok project, you have to perform
three steps:

1) Mark your doctests with either::

     :Test-Layer: functional

   or::

     :Test-Layer: unit

   Choose the first term, if your file contains functional tests, the 
   latter term, if it contains unit tests.

2) Setup testing.

   Create a Python file whose name starts with 'tests' in your app. For 
   example `tests.py`, `tests_myapp.py` or `tests_setup.py`.

   Populate this file with your tests' setup.

   This normally is a bit complicated and you have to remember several 
   things/commands/options etc. The shortest setup you can use now looks
   like this::

       import unittest
       import grok
       import cave # The package that contains the doctest files

       def test_suite():
           setup = grok.testing.UnitTestSetup(cave)
           return setup.getTestSuite()

       if __name__ == '__main__':
           unittest.main(default='test_suite')

   This will search your ``cave`` package (including subdirectories) 
   for any .rst or .txt files, that contain the testlayer marker string 
   as mentioned above and will register the files as doctests.

   You want to setup unittests and functional tests once in a row? Here 
   we go::

       import unittest
       import grok
       import cave # The package that contains the doctest files

       def test_suite():
           suite = unittest.TestSuite()
           suite.addTest( # Add all unittests from `cave`
               grok.testing.UnitTestSetup(cave).getTestSuite())
           suite.addTest( # Add all functional tests from `cave`
               grok.testing.FunctionalTestSetup(cave).getTestSuite())
           return suite

       if __name__ == '__main__':
           unittest.main(default='test_suite')

   This step normally must be done only once.

3) Run the tests

   Given you act in a grokproject environment, then, after the setup is 
   finished you can run::

	$ bin/test

   from your project root and all tests should be run. Other 
   environments might behave similar.

There is about one zillion of possibilities to change the default
behaviour of `UnitTestSetup` and `FunctionalTestSetup`. You can change
the filename extensions to look for, the `globs`, the tearDown-methods,
the marker strings and many, many more.

You can (and should, if you use it) read more about it in the test files
of this extension:

	http://svn.zope.org/grok/trunk/src/grok/tests/testsetup/

Documentation on the grok site will follow in the next days if no
serious objections or changes should happen.

Hope that helps,

-- 
Uli