[Checkins] SVN: z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt Update docs.

[Uli Fouquet]

Log message for revision 94527:
  Update docs.

Changed:
  U   z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt

-=-
Modified: z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt
===================================================================
--- z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt	2009-01-05 10:32:04 UTC (rev 94526)
+++ z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt	2009-01-05 10:32:26 UTC (rev 94527)
@@ -95,12 +95,16 @@
       Set up z3c...layer.DefaultZCMLLayer [ftesting2.zcml] in N.NNN seconds.
       Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
       Tear down z3c...layer.DefaultZCMLLayer [ftesting2.zcml] ... not supported
-    Running z3c.testsetup.tests.othercave.testing.UnitLayer1 tests:
+    Running z3c.testsetup.tests.othercave.testing.UnitLayer2 tests:
       Running in a subprocess.
       Set up z3c.testsetup.tests.othercave.testing.UnitLayer1 in N.NNN seconds.
+      Set up z3c.testsetup.tests.othercave.testing.UnitLayer2 in N.NNN seconds.
         Running testSetUp of UnitLayer1
+        Running testSetUp of UnitLayer2
+        Running testTearDown of UnitLayer2
         Running testTearDown of UnitLayer1
       Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
+      Tear down z3c...tests.othercave.testing.UnitLayer2 in N.NNN seconds.
       Tear down z3c...tests.othercave.testing.UnitLayer1 in N.NNN seconds.
     Running zope.testing.testrunner.layer.UnitTests tests:
       Running in a subprocess.
@@ -111,3 +115,124 @@
       Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
     Total: 7 tests, 0 failures, 0 errors in N.NNN seconds.
     False
+
+As we can see, there were regular unittests as well as functional
+tests run. Some of the unittests used their own layer (``UnitLayer1``)
+whose location were printed and the functional tests used different
+ZCML-files for configuration.
+
+Of course, there were more tests than only the ones defined in
+``doctest01.txt``. Let's have a look at the other stuff.
+
+
+Setting up a unittest layer
+===========================
+
+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``)::
+
+    A doctests with layer
+    =====================
+    <BLANKLINE>
+    :doctest:
+    :layer: z3c.testsetup.tests.othercave.testing.UnitLayer2
+    <BLANKLINE>
+      >>> 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 
+
+ `:layer:`
+
+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::
+
+  >>> print open(os.path.join(cavepath, 'testing.py')).read()
+  import os
+  ...
+  class UnitLayer1(object):
+      """This represents a layer.
+      A layer is a way to have common setup and teardown that happens
+      once for a whole group of tests.
+  <BLANKLINE>
+      It must be an object with a `setUp` and a `tearDown` method, which
+      are run once before or after all the tests applied to a layer
+      respectively.
+  <BLANKLINE>
+      Optionally you can additionally define `testSetUp` and
+      `testTearDown` methods, which are run before and after each single
+      test.
+  <BLANKLINE>
+      This class is not instantiated. Therefore we use classmethods.
+      """
+  <BLANKLINE>
+      @classmethod
+      def setUp(self):
+          """This gets run once for the whole test run, or at most once per
+          TestSuite that depends on the layer.
+          (The latter can happen if multiple suites depend on the layer
+          and the testrunner decides to tear down the layer after first
+          suite finishes.)
+          """
+  <BLANKLINE>
+      @classmethod
+      def tearDown(self):
+          """This gets run once for the whole test run, or at most
+          once per TestSuite that depends on the layer,
+          after all tests in the suite have finished.
+          """
+  <BLANKLINE>
+      @classmethod
+      def testSetUp(self):
+          """This method is run before each single test in the current
+          layer. It is optional.
+          """
+          print "    Running testSetUp of UnitLayer1"
+  <BLANKLINE>
+      @classmethod
+      def testTearDown(self):
+          """This method is run before each single test in the current
+          layer. It is optional.
+          """
+          print "    Running testTearDown of UnitLayer1"
+  <BLANKLINE>
+  class UnitLayer2(UnitLayer1):
+      """This Layer inherits ``UnitLayer1``.
+  <BLANKLINE>
+      This way we define nested setups. During test runs the testrunner
+      will first call the setup methods of ``UnitTest1`` and then those
+      of this class. Handling of teardown-methods will happen the other
+      way round.
+      """
+  <BLANKLINE>
+      @classmethod
+      def setUp(self):
+          pass
+  <BLANKLINE>
+      @classmethod
+      def testSetUp(self):
+          print "    Running testSetUp of UnitLayer2"
+  <BLANKLINE>
+      @classmethod
+      def testTearDown(self):
+          print "    Running testTearDown of UnitLayer2"
+
+In a layer you can do all the special stuff that is needed to run a
+certain group of tests properly. Our setup here is special in that we
+defined a nested one: ``UnitLayer2`` inherits ``UnitLayer1`` so that
+during test runs the appropriate setup and teardown methods are called
+(see testrunner output above).
+
+More about test layers can be found at the documentation of
+`testrunner layers API
+<http://apidoc.zope.org/++apidoc++/Code/zope/testing/testrunner-layers-api.txt/index.html>`_.
+