[Checkins] SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/ More custom ZCML layer docs.

[Uli Fouquet]

Log message for revision 83453:
  More custom ZCML layer docs.

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

-=-
Modified: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/functionaldoctestsetup.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/functionaldoctestsetup.txt	2008-02-03 14:16:01 UTC (rev 83452)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/functionaldoctestsetup.txt	2008-02-03 14:16:41 UTC (rev 83453)
@@ -164,8 +164,8 @@
 
 Because functional tests require a ZCML layer, that defines a ZCML
 setup for the tests, we provide a layer, that is driven by the file
-`ftesting.zcml`, which comes with grok. The layer is accessible as the
-setup instance attribute `layer`::
+`ftesting.zcml`, which comes with `z3c.testsetup`. The layer is
+accessible as the setup instance attribute `layer`::
 
    >>> setup.layer
    <zope.app.testing.functional.ZCMLLayer instance at 0x...>
@@ -173,7 +173,6 @@
    >>> setup.layer.config_file
    '...ftesting.zcml'
 
-   
 
 No other options/parameters are set by default.
 
@@ -251,6 +250,26 @@
 extensions.
 
 
+Customizing the functional doctest ZCML layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ZCML layer registered by default by ``z3c.testsetup`` is very
+poor. In fact it only exists, to satisfy dependencies. In most cases,
+you would like to write your own ZCML configuration to register
+principals etc. during functional doctests.
+
+For this purpose, ``FunctionalDocTestSetup`` supports the constructor
+parameters `zcml_config` and `layer_name`. If the first is set, then
+the ZCML file denoted by the path in this variable will be used
+instead of the dummy ZCML contained in ``z3c.testsetup``.
+
+   >>> setup_w_custom_layer = FunctionalDocTestSetup(
+   ...     cave,
+   ...     zcml_config = 'sampleftesting.zcml')
+   >>> pnorm(setup_w_custom_layer.layer.config_file)
+   '.../tests/cave/sampleftesting.zcml'
+   
+
 Customizing the functional test setup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -284,5 +303,4 @@
     >>> encoded_setup.additional_options['encoding'] = 'latin1'
 
 
-
 """

Modified: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt	2008-02-03 14:16:01 UTC (rev 83452)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt	2008-02-03 14:16:41 UTC (rev 83453)
@@ -180,13 +180,13 @@
     >>> from zope.testing import testrunner
     >>> testrunner.run(defaults)
     Running unit tests:
-      Ran 2 tests with 0 failures and 0 errors in 0.001 seconds.
+      Ran 2 tests with 0 failures and 0 errors in ... seconds.
     Running z3c.testsetup.tests.cave.SampleLayer tests:
-      Set up z3c.testsetup.tests.cave.SampleLayer in 0.005 seconds.
-      Ran 2 tests with 0 failures and 0 errors in 0.001 seconds.
+      Set up z3c.testsetup.tests.cave.SampleLayer in ... seconds.
+      Ran 2 tests with 0 failures and 0 errors in ... seconds.
     Tearing down left over layers:
       Tear down z3c.testsetup.tests.cave.SampleLayer ... not supported
-    Total: 4 tests, 0 failures, 0 errors in 0.055 seconds.
+    Total: 4 tests, 0 failures, 0 errors in ... seconds.
     False
 
 Apparently now the custom ZCML file in the ``cave`` package was used.