[Checkins] SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/pythontestsetup.txt More python testsetup tests.

[Uli Fouquet]

Log message for revision 83801:
  More python testsetup tests.

Changed:
  U   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/pythontestsetup.txt

-=-
Modified: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/pythontestsetup.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/pythontestsetup.txt	2008-02-13 16:04:08 UTC (rev 83800)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/pythontestsetup.txt	2008-02-13 16:04:35 UTC (rev 83801)
@@ -118,3 +118,115 @@
 Only files, that meet all three conditions are searched for tests.
 You can modify this behaviour of course, which will be explained below
 in detail.
+
+
+What options are set by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because normal Python tests do the setup of tests themselves, there is
+not much to configure. Tests are just picked up and have to provide
+their own setup and teardown methods.
+
+For the finding of tests, however, two options can be set:
+
+- ``regexp_list`` is a list of regular expressions, that must be
+  matched by at least one line of a potential test module each.
+
+- ``pfilter_func`` is a function that uses ``regexp_list`` to filter
+  accepted files. You can do your own filtering by passing a different
+  function here. By default the instance method ``isTestModule`` is
+  used, that expects a module as parameter and return True or False
+  depending on whether the terms in ``regexp_list`` could all be found
+  or not.
+
+
+Customizing python test setup:
+------------------------------
+
+You can modify the behaviour of ``z3c.testsetup.UnitTestSetup`` such,
+that a different set of modules is registered. Customizing of each
+test setup is not supported by now. This means, you can say **which**
+modules are registered, but not **how** they are registered. This is
+not the case for doctest setups.
+
+Customizing the module search:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The searching for appropriate test modules is basically done by the
+two methods ``getModules`` and ``isTestModule``. The latter does
+additional checking. Namely it checks for the existance of the above
+mentioned ReStructured Text meta-marker::
+
+    `:Test-Layer: python`
+
+This marker is determined by a list of regular expressions, which is
+also available as an object attribute::
+
+    >>> setup.regexp_list
+    ['^\\s*:(T|t)est-(L|l)ayer:\\s*(python)\\s*']
+
+This is the default value of Python unit test setups.
+
+There is one module in the `cave` subpackage, which provides that
+marker. We can get the list of modules using `getModules()``::
+
+    >>> module_list = setup.getModules()
+    >>> module_list
+    [<module 'z3c.testsetup.tests.cave.file1' from ...>]
+
+    >>> len(module_list)
+    1
+
+The ``isTestModule()`` method of our setup object did the filtering
+here::
+
+    >>> setup.isTestModule(module_list[0])
+    True
+
+The module ``notatest2`` of the ``cave`` package does not contain a
+Python test marker::
+
+    >>> from z3c.testsetup.tests.cave import notatest2
+    >>> setup.isTestModule(notatest2)
+    False
+
+The ``regexp_list`` attribute of a ``UnitTestSetup`` contains a list
+of regular expressions, of which each one must at least match one line
+of the docstring of a module to be accepted. If you want to include
+modules with different marker-strings, just change this attribute. The
+value will influence behaviour of the `isTestModule()``,
+``getModules()`` and ``getTestSuite()`` methods.
+
+Let's see, how this works. The notatest2 module contains a string::
+
+  :Test-Layer: False
+
+and we want its tests to be registered::
+
+    >>> setup.regexp_list = ['^\\s*:(T|t)est-(L|l)ayer:\\s*(F|false)\\s*']
+
+Now we fetch the module list again::
+
+    >>> module_list = setup.getModules()
+    >>> module_list
+    [<module 'z3c.testsetup.tests.cave.notatest2' from ...>]
+
+    >>> len(module_list)
+    1
+
+This time, the ``file1`` module was skipped. Finally let's make sure,
+that the new setting is considered when getting a test suite::
+
+    >>> suite = setup.getTestSuite()
+    >>> get_basenames_from_suite(suite)
+    ['notatest2.py']
+
+Note, that the terms in ``regexp_list`` must match **all**. Therefore,
+if you want to match one of several possible markers, then you need
+one regular expression that matches each of the possible terms but no
+others.
+
+If you need more complex checks here, you can derive your customized
+test setup class and overwrite ``isModule()``.
+
+