[Checkins] SVN: z3c.testsetup/branches/ulif-cleanup/src/z3c/testsetup/layered_setups.txt Add samples for layered setups in separate test file.

[Uli Fouquet]

Log message for revision 105252:
  Add samples for layered setups in separate test file.
  

Changed:
  A   z3c.testsetup/branches/ulif-cleanup/src/z3c/testsetup/layered_setups.txt

-=-
Added: z3c.testsetup/branches/ulif-cleanup/src/z3c/testsetup/layered_setups.txt
===================================================================
--- z3c.testsetup/branches/ulif-cleanup/src/z3c/testsetup/layered_setups.txt	                        (rev 0)
+++ z3c.testsetup/branches/ulif-cleanup/src/z3c/testsetup/layered_setups.txt	2009-10-24 12:45:35 UTC (rev 105252)
@@ -0,0 +1,100 @@
+z3c.testsetup and layers
+------------------------
+
+Here we discuss complete testsetups that involve test layers. Test
+layers are a method to group several tests or test suites in groups.
+
+Layers are a method to do time-consuming setups like initializing
+databases or whatever only once for a whole bunch of tests. Such you
+can save time and make your testing setup less error-prone.
+
+See `layered_cave/layer.py` for examples of working layers. We will
+use the layers defined there in the following examples.
+
+Simple unit doctests with layers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using z3c.testsetup, we can define quite complex testsetups with only
+three lines of code::
+
+    >>> import os
+    >>> cavepath = os.path.join(os.path.dirname(__file__), 'tests', 
+    ...   'layered_cave')
+    >>> setupfile = os.path.join(cavepath, 'layeredsetup01.py')
+    >>> print open(setupfile).read()
+    from z3c.testsetup import register_all_tests
+    test_suite = register_all_tests('z3c.testsetup.tests.layered_cave')
+
+We clear the commandline, because all parameters passed to the
+commandline would otherwise be applied to the examples herein::
+
+    >>> import sys
+    >>> sys.argv = [sys.argv[0],]
+
+This means, that we want to register all tests (doctests and 'normal'
+python tests) from the ``layered_cave`` package, whose name we passed in
+dotted name notation as a string. This is enough information for a
+testrunner.
+
+In one of the test files we declared, that a layer should be used::
+
+    >>> testfile = os.path.join(cavepath, 'adoctest.txt')
+    >>> print open(testfile, 'r').read()
+    This is a doctest
+    =================
+    <BLANKLINE>
+    This doctest will be applied to a layer.
+    <BLANKLINE>
+    :doctest:
+    :layer: z3c.testsetup.tests.layered_cave.layer.UnitLayer1
+    ...
+
+The line saying `:layer:` tells, that we want the layer denoted by the
+trailing dotted name should be applied to the tests of the file. It is
+vital that the denoted object really exist. The format of the layer
+declaration is::
+
+  :layer: <dotted.name.of.layer.definition>
+
+where the marker string can be written in upper or lower or mixed
+case. Doing so, the testrunner will apply the declared layer to our
+tests.
+
+To make things more interesting we also created two subpackages in our
+package, named ``foo`` and ``bar``. Both contain functional doctests
+that need separate ZCML code for initialization and use the default
+layer. Although both ZCML files are called ``ftesting.zcml`` the
+setups will run isolated from each other::
+
+    >>> from z3c.testsetup import testrunner
+    >>> defaults = [
+    ...     '--path', cavepath, '-f',
+    ...     '--tests-pattern', '^layeredsetup01$',
+    ...     ]
+    >>> testrunner.run(defaults)
+    Running z3c...DefaultZCMLLayer [/layered_cave/bar/ftesting.zcml] tests:
+      Set up z3c...Layer [/layered_cave/bar/ftesting.zcml] in N.NNN seconds.
+      Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
+    Running z3c...DefaultZCMLLayer [/layered_cave/foo/ftesting.zcml] tests:
+      Tear down z3c...Layer [/layered_cave/bar/ftesting.zcml] ... not supported
+      Running in a subprocess.
+      Set up z3c...Layer [/layered_cave/foo/ftesting.zcml] in N.NNN seconds.
+      Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
+      Tear down z3c...Layer [/layered_cave/foo/ftesting.zcml] ... not supported
+    Running z3c.testsetup.tests.layered_cave.layer.FunctionalLayer1 tests:
+      Running in a subprocess.
+      Set up z3c...layer.FunctionalLayer1 in N.NNN seconds.
+      Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
+      Tear down z3c...FunctionalLayer1 in N.NNN seconds.
+    Running z3c.testsetup.tests.layered_cave.layer.UnitLayer1 tests:
+      Running in a subprocess.
+      Set up z3c...tests.layered_cave.layer.UnitLayer1 in N.NNN seconds.
+        Running testSetUp of UnitLayer1
+        Running testTearDown of UnitLayer1
+      Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
+      Tear down z3c...tests.layered_cave.layer.UnitLayer1 in N.NNN seconds.
+    Total: 4 tests, 0 failures, 0 errors in N.NNN seconds.
+    False
+
+As we can see, the layer `UnitLayer1` was executed here.
+