[Checkins]
SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testgetter.txt
Tests for the testgetters.
Uli Fouquet
uli at gnufix.de
Wed Feb 13 06:38:28 EST 2008
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.
More information about the Checkins
mailing list