[Checkins] SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt Tests for the testgetters.

[Uli Fouquet]

Log message for revision 83783:
  Tests for the testgetters.

Changed:
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt

-=-
Added: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt	                        (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt	2008-02-13 11:38:28 UTC (rev 83783)
@@ -0,0 +1,102 @@
+===========
+TestGetters
+===========
+
+Convenience stuff to setup reusable test collectors.
+
+Test getters are intended to be called by unittest testrunners and
+should return a test suite.
+
+Normally, you might setup tests with z3c.testsetup calling
+``z3c.testsetup.register_all_tests()`` or similar functions. If your
+test setup requires no or little customization, this might be
+sufficient.
+
+If, however, you want to do more complex setups, that require lots of
+parameters and that have to be done for several setups, this approach
+might get cumbersome: you have to pass all parameters for every test
+setup module or to write your own wrapper functions, which will take
+all the time you saved with the usage of z3c.testsetup before. This
+is, where ``TestGetters`` come to help.
+
+They should provide a more convenient 'framework' to setup customized
+setups, which are reusable.
+
+Normally, you register tests with z3c.testsetup like this::
+
+   >>> import z3c.testsetup
+   >>> test_suite = z3c.testsetup.register_all_tests(
+   ...     'z3c.testsetup.tests.cave')
+
+A testrunner, if it finds that code in a testsetup module, will look
+for the ``test_suite`` callable and call it to get a
+``unittest.TestSuite``::
+
+   >>> test_suite()
+   <unittest.TestSuite tests=[...]>
+
+To tweak the tests run, we can pass keyword parameters to the
+``register_all_tests`` function. But what, if we maintain a package,
+that requires lots of those keyword parameters? What, if we defined
+our own TestSetup type derived from the originals?
+
+Well, we can of course write our own function, that checks all passed
+parameters, filters/modifies them for every test type respectively and
+then does the testsetup for every single kind of test type 'manually'.
+
+This can become quite cumbersome.
+
+The basic test getter can be used like this::
+
+   >>> from z3c.testsetup import TestGetter
+   >>> getter = TestGetter('z3c.testsetup.tests.cave')
+   >>> getter
+   <z3c.testsetup.testgetter.TestGetter object at 0x...>
+
+The package can passed as string in 'dotted name' notation or as real
+package::
+
+   >>> from z3c.testsetup.tests import cave
+   >>> getter = TestGetter(cave)
+   >>> getter
+   <z3c.testsetup.testgetter.TestGetter object at 0x...>
+
+If we call that getter, we should get a ``unittest.TestSuite``::
+
+   >>> suite = getter()
+   >>> suite
+   <unittest.TestSuite tests=[...]>
+
+This standard suite does not include the functional doctest file
+``notatest1.foo`` which is in the cave package::
+
+   >>> get_basenames_from_suite(suite)
+   ['file1.py', 'file1.rst', 'file1.txt', 'subdirfile.txt']
+
+All this looks quite similar to the setup with regular functions. So
+why not use a simple modified function or a wrapper function? Let's
+see, what happens, if we want to define a function, that registers by
+default .foo-files for functional doctests. This can be done like
+this::
+
+   >>> from z3c.testsetup import register_all_tests
+   >>> def register_foo(pkg, *args, **kw):
+   ...    fext = ['.foo',]
+   ...    if 'fextensions' in kw.keys():
+   ...       fext = kw['fextensions']
+   ...       del kw['fextensions']
+   ...    return register_all_tests(pkg, fextensions=fext, **kw)
+   >>> suite = register_foo(cave)()
+   >>> get_basenames_from_suite(suite)
+   ['file1.py', 'file1.rst', 'notatest1.foo']
+
+With a ``TestGetter`` you can archieve the same effect like this::
+
+   >>> class FooTestGetter(TestGetter):
+   ...     defaults = {'fextensions': ['.foo',]}
+   >>> suite = FooTestGetter(cave)()
+   >>> get_basenames_from_suite(suite)
+   ['file1.py', 'file1.rst', 'notatest1.foo']
+
+Despite the fact, that this notation is easier to read than the
+function above, it is also easier to reuse.