[Checkins] SVN: z3c.testsetup/trunk/s removed testrunner.txt from the long description: mostly internals that

Reinout van Rees reinout at vanrees.org
Tue Sep 22 04:40:59 EDT 2009


Log message for revision 104418:
  removed testrunner.txt from the long description: mostly internals that
  otherwise clutter up the pypi documentation.
  Moved some explanation to the main README, however.

Changed:
  U   z3c.testsetup/trunk/setup.py
  U   z3c.testsetup/trunk/src/z3c/testsetup/README.txt
  U   z3c.testsetup/trunk/src/z3c/testsetup/testrunner.txt

-=-
Modified: z3c.testsetup/trunk/setup.py
===================================================================
--- z3c.testsetup/trunk/setup.py	2009-09-22 07:51:06 UTC (rev 104417)
+++ z3c.testsetup/trunk/setup.py	2009-09-22 08:40:59 UTC (rev 104418)
@@ -17,8 +17,6 @@
     + '\n\n'
     + read('src', 'z3c', 'testsetup', 'HOWTO_UPGRADE.txt')
     + '\n\n'
-    + read('src', 'z3c', 'testsetup', 'testrunner.txt')
-    + '\n\n'
     + read('CHANGES.txt')
     + '\n\n'
     + 'Download\n'

Modified: z3c.testsetup/trunk/src/z3c/testsetup/README.txt
===================================================================
--- z3c.testsetup/trunk/src/z3c/testsetup/README.txt	2009-09-22 07:51:06 UTC (rev 104417)
+++ z3c.testsetup/trunk/src/z3c/testsetup/README.txt	2009-09-22 08:40:59 UTC (rev 104418)
@@ -313,8 +313,8 @@
 
 - **checker**:
 
-    An output checker for doctests. `None` by default. A typical
-    output checker can be created like this::
+    An output normalizer for doctests. `None` by default. A typical output
+    checker can be created like this::
 
       >>> import re
       >>> from zope.testing import renormalizing
@@ -329,11 +329,12 @@
 
       <SOME NUBMER OF> seconds
 
-    Please see ``testrunner.txt`` for examples of usage.
+    Define this checker in your testrunner .py file and add a
+    ``checker=mychecker`` option to the ``register_all_tests()`` call.  Since
+    version 0.5 checkers are applied to both regular and functional doctests
+    (pre-0.5: only functional ones).
 
-    Checkers are applied to functional doctests only!
 
-
 - **globs**:
 
     A dictionary of things that should be available immediately
@@ -344,7 +345,8 @@
     This parameter is a fallback which can be overriden by testfile
     markers specifying a certain layer (see below).
 
-    The `globs` parameter applies only to doctests.
+    The `globs` parameter applies only to doctests, not to plain python
+    unittests.
 
 
 - **optionflags**:
@@ -384,6 +386,23 @@
     way.
 
 
+- **allow_teardown**:
+
+    A boolean whether teardown of zcml layers is allowed (*added in 0.5*).  In
+    rare corner cases (like programmatically slapping an interface on a
+    class), a full safe teardown of the zope component architecture is
+    impossible.  Zope.testing has a default setting for allow_teardown of
+    False, which means it uses the safe default of running every zcml layer in
+    a separate process, which ensures full teardown.
+
+    The drawback is that profiling and coverage tools cannot combine the
+    profile/coverage data from separate processes.  z3c.testsetup has a
+    default of True (since 0.5), which gives you correct coverage/profiling
+    output.  If you do one of the rare things that can trip up a regular
+    teardown of the zope component architecture, you'll have to set
+    ``allow_teardown=False`` in your ``register_all_tests()`` call.
+
+
 - **zcml_config**:
 
     A filepath of a ZCML file which is registered with functional
@@ -410,7 +429,7 @@
     given or a docfile specifies its own layer/ZCML config (see
     below).
 
-    This is a fallback parameter. Use of docfile specific layer
+    This is a fallback parameter. Use of per-doctest-file specific layer
     markers is recommended.
 
 - **layer**:
@@ -477,18 +496,17 @@
 See further below for explanations of the respective markers.
 
 
-Setting up a unittest layer: ``:layer:``
-----------------------------------------
+Setting up a self-defined layer: ``:layer:``
+--------------------------------------------
 
-Starting with ``z3c.testsetup`` 0.3 there is first reasonable support
-for setting up layers per testfile. This way you can easily create
-setup-functions that are only run before/after certain tests.
+Starting with ``z3c.testsetup`` 0.3 there is reasonable support for setting up
+layers per testfile. This way you can easily create setup-functions that are
+only run before/after certain sets tests.
 
 Overall, use of layers is the recommended way from now on.
 
-We can tell ``z3c.testsetup`` to use a certain unittest layer using
-the ``:layer:`` marker as in the following example (see
-``tests/othercave/doctest02.txt``)::
+We can tell ``z3c.testsetup`` to use a certain layer using the ``:layer:``
+marker as in the following example (see ``tests/othercave/doctest02.txt``)::
 
     A doctests with layer
     =====================
@@ -499,18 +517,14 @@
       >>> 1+1
       2
 
-
 The ``:doctest:`` marker was used here as well, because without it the
 file would not have been detected as a registerable doctest file (we
 want developers to be explicit about that).
 
-The 
+The ``:layer: <DOTTED_NAME_OF_LAYER_DEF>`` marker then tells, where the
+testsetup machinery can find the layer definition. It is given in dotted name
+notation and points to a layer you defined yourself.
 
- `:layer: <DOTTED_NAME_OF_LAYER_DEF>`
-
-marker then tells, where the testsetup machinery can
-find the layer definition. It is given in dotted name notation.
-
 How does the layer definition look like? It is defined as regualr
 Python code::
 
@@ -597,11 +611,11 @@
 Specifying a ZCML file: ``:zcml-layer:``
 ----------------------------------------
 
-When it comes to integration or functional tests, we need to specify a
-ZCML file to which configures the test environment for us. We can do
-that using the
+When it comes to integration tests which use zope's component architecture, we
+need to specify a ZCML file which configures the test environment for us. We
+can do that using the
 
-  `:zcml-layer: <ZCML-file-name>`
+  ``:zcml-layer: <ZCML-file-name>``
 
 marker. It expects a ZCML filename as argument and sets up a
 ZCML-layered testsuite for us. An example setup might look like so (see
@@ -622,13 +636,14 @@
    be available when running the tests and during test setup. This
    package is not fetched by default by ``z3c.testsetup``.
 
-Here we say, that the the local file ``ftesting.zcml`` should be used
-as ZCML configuration. As we can see in the above output of testruner,
-this file is indeed read during test runs and used by a ZCML layer
-called ``DefaultZCMLLayer``. This layer is in fact only a
+Here we say that the the local file ``ftesting.zcml`` should be used as ZCML
+configuration. As we can see in the above output of testruner, this file is
+indeed read during test runs and used by a ZCML layer called
+``DefaultZCMLLayer``. This layer is in fact only a
 ``zope.app.testing.functional.ZCMLLayer``.
 
-The ZCML file is looked up in the same directory as the doctest file.
+The ZCML file is looked up in the same directory as the doctest file. (You can
+use relative paths like ``../ftesting.zcml`` just fine, btw).
 
 When using the ``:zcml-layer:`` marker, the concerned tests are set up
 via special methods and functions from `zope.app.testing`. This way
@@ -742,3 +757,5 @@
 As we can see, there is a function ``myfunc`` pulled into the
 namespace of the doctest. We could, however, do arbitrary other things
 here, set up a relational test database or whatever.
+
+

Modified: z3c.testsetup/trunk/src/z3c/testsetup/testrunner.txt
===================================================================
--- z3c.testsetup/trunk/src/z3c/testsetup/testrunner.txt	2009-09-22 07:51:06 UTC (rev 104417)
+++ z3c.testsetup/trunk/src/z3c/testsetup/testrunner.txt	2009-09-22 08:40:59 UTC (rev 104418)
@@ -1,4 +1,4 @@
-Setup Examples
+Setup examples
 ==============
 
 Here we discuss complete test setups for the `cave` package contained
@@ -365,7 +365,7 @@
     True
 
 Note that in older versions of `z3c.testsetup` checkers were supported
-for functioanl doctests only.
+for functional doctests only.
 
 
 Setting globals for doctests
@@ -625,8 +625,8 @@
 
 As we can see, the layer `UnitLayer1` was executed here.
 
-Convenience Stuff
-=================
+Convenience stuff for testers of z3c.testsetup
+==============================================
 
 Here we collect some convenience stuff, that might be useful for
 testers. Most people, however, won't need them.



More information about the checkins mailing list