[Checkins] SVN: z3c.testsetup/trunk/ reordered the main documentation
Reinout van Rees
reinout at vanrees.org
Tue Sep 22 03:46:17 EDT 2009
Log message for revision 104416:
reordered the main documentation
Changed:
U z3c.testsetup/trunk/CHANGES.txt
U z3c.testsetup/trunk/src/z3c/testsetup/README.txt
-=-
Modified: z3c.testsetup/trunk/CHANGES.txt
===================================================================
--- z3c.testsetup/trunk/CHANGES.txt 2009-09-22 05:53:25 UTC (rev 104415)
+++ z3c.testsetup/trunk/CHANGES.txt 2009-09-22 07:46:16 UTC (rev 104416)
@@ -1,5 +1,5 @@
-CHANGES
-*******
+Changelog for z3c.testsetup
+***************************
0.5 (unreleased)
================
@@ -16,6 +16,8 @@
derived from `zope.testing.functional.ZCMLLayer`, then the test is
set up with the same kind of testcase as ``:functional-zcml-layer:``.
+* Reordered and cleaned up the documentation.
+
Feature changes
---------------
Modified: z3c.testsetup/trunk/src/z3c/testsetup/README.txt
===================================================================
--- z3c.testsetup/trunk/src/z3c/testsetup/README.txt 2009-09-22 05:53:25 UTC (rev 104415)
+++ z3c.testsetup/trunk/src/z3c/testsetup/README.txt 2009-09-22 07:46:16 UTC (rev 104416)
@@ -32,15 +32,19 @@
Basic Example
=============
-Before we can find, register and execute tests, we first have to write
-them down. We already have some ready to use tests available, which
-can be found in a subpackage:
+Before we can find, register and execute tests, we first have to write them
+down. z3c.testsetup includes examples used for testing (you can find them all
+in the ``tests/`` subdirectory if you've downloaded the source code):
>>> import os
>>> cavepath = os.path.dirname(__file__)
>>> cavepath = os.path.join(cavepath, 'tests', 'othercave')
-In this subpackage there is a simple doctest `doctest01.txt` (please
+
+Registering doctests
+--------------------
+
+In this example directory, there is a simple doctest `doctest01.txt` (please
ignore the pipes on the left):
>>> print_file(os.path.join(cavepath, 'doctest01.txt'))
@@ -66,45 +70,6 @@
you want to disable a test, just turn ``:doctest:`` into ``:nodoctest:`` (or
something else) and the file will be ignored.
-Other markers detected by ``z3c.testsetup`` are:
-
-- ``:unittest:``
-
- A replacement for ``:doctest:``, marking a Python module as
- containing unittests to run. Replaces old ``Test-Layer: python``
- marker.
-
-- ``:setup: <dotted.name.of.function>``
-
- Execute the given setup function before running doctests in this
- file.
-
-- ``:teardown: <dotted.name.of.function>``
-
- Execute the given teardown function after running doctests in this
- file.
-
-- ``:layer: <dotted.name.of.layer.def>``
-
- Use the given layer definition for tests in this file. If the layer
- given is derived from `zope.testing.functional.ZCMLLayer`, the test
- is registered using `zope.app.testing.functional.DocFileSuite`.
-
-- ``:zcml-layer: <ZCML_filename>``
-
- Use the given ZCML file and run tests in this file on a ZCML
- layer. Tests are registered using
- `zope.testing.doctest.DocFileSuite`.
-
-- ``:functional-zcml-layer: <ZCML_filename>``
-
- Use the given ZCML file and run tests in this file registered with
- `zope.app.testing.functional.DocFileSuite`.
-
-Markers are case-insensitive.
-
-See below for explanations of the respective markers.
-
.. note:: How to disable markers or make them invisible
All markers can be written as restructured text comments (two leading dots
@@ -116,11 +81,11 @@
from autogenerated docs etc.
-Now, that we have a doctest available, we can write a testsetup
-routine, that collects all tests, registers them and passes them to
-the testrunner.
+Running the tests
+-----------------
-We have such a simple testsetup already available::
+Now that we have a doctest available, we can write a testsetup routine that
+collects all tests, registers them and passes them to the testrunner:
>>> print open(os.path.join(cavepath, 'simplesetup01.py')).read()
import z3c.testsetup
@@ -128,13 +93,10 @@
'z3c.testsetup.tests.othercave')
This is all we need in simple cases. We use
+``register_all_tests(<dotted_pkg_name>)`` to tell the setup machinery, where
+to look for test files. Note that also files in subpackages will be found,
+registered and executed when they are marked approriately.
- `register_all_tests(<dotted_pkg_name>)`
-
-to tell the setup machinery, where to look for test files. Note, that
-also files in subpackages will be found, registered and executed, when
-they are marked approriately.
-
Let's start the testrunner and see what it gives::
>>> import sys
@@ -177,22 +139,19 @@
Total: 13 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.
+As we can see, there were regular unittests as well as functional tests
+run. Some of the unittests used their own layer (``UnitLayer1``). Layers are
+shown in the output. In this example, the functional tests use different
+ZCML-files for configuration which results in separate test layers.
-Of course, there were more tests than only the ones defined in
-``doctest01.txt``. Let's have a look at the other stuff.
+Finding doctests in Python modules
+----------------------------------
-Defining doctests in Python modules
------------------------------------
-
The doctest file described above was a pure .txt file. By default
``z3c.testsetup`` looks for doctests in files with filename extension
``.txt``, ``.rst`` and ``.py``. This means, that also doctests in
-Python modules are found by default as in the following example::
+Python modules are found just fine as in the following example:
>>> print_file(os.path.join(cavepath, 'doctest08.py'))
| """
@@ -242,12 +201,12 @@
from the very same file if you want to use them.
-Registering regular unittests from Python modules
--------------------------------------------------
+Registering regular python unittests
+------------------------------------
``z3c.testsetup`` provides also (limited) support for regular
`unittest` deployments as usually written in Python. An example file
-could look like this::
+looks like this:
>>> print_file(os.path.join(cavepath, 'pythontest1.py'))
| """
@@ -269,13 +228,11 @@
|
|
-The module contains a marker ``:unittest:`` in its module docstring
-instead of the ``:doctest:`` marker used in the other examples
-above. It is also the replacement for the formely used ``:Test-Layer:
-python`` marker.
+The module contains a marker ``:unittest:`` in its module docstring instead of
+the ``:doctest:`` marker used in the other examples above. This means that
+the file is registered as a regular unittest. (It is also the replacement for
+the formely used ``:Test-Layer: python`` marker.)
-This means, that this file is registered as a regular unittest.
-
If you use unittests instead of doctests, then you are mainly on your
own with setting up and tearing down tests. All this should be done by
the test cases themselves.
@@ -284,8 +241,8 @@
tests are found and run automatically when they provide the marker.
-``register_all_tests()``
-========================
+Registering the tests: ``register_all_tests()``
+===============================================
The `register_all_tests` function mentioned above accepts a bunch of
keyword parameters::
@@ -492,19 +449,58 @@
``fextensions``, etc.) is running out and its use deprecated.
-Layers and setup/teardown functions
-===================================
+Available markers for configuring the tests
+===========================================
+We already saw the ``:doctest:`` marker above. Other markers detected by
+``z3c.testsetup`` are:
+
+- ``:unittest:``
+
+ A replacement for ``:doctest:``, marking a Python module as containing
+ unittests to run. (Replaces old ``Test-Layer: python`` marker.)
+
+- ``:setup: <dotted.name.of.function>``
+
+ Execute the given setup function before running doctests in this
+ file.
+
+- ``:teardown: <dotted.name.of.function>``
+
+ Execute the given teardown function after running doctests in this
+ file.
+
+- ``:layer: <dotted.name.of.layer.def>``
+
+ Use the given layer definition for tests in this file. If the layer
+ given is derived from `zope.testing.functional.ZCMLLayer`, the test
+ is registered using `zope.app.testing.functional.DocFileSuite`.
+
+- ``:zcml-layer: <ZCML_filename>``
+
+ Use the given ZCML file and run tests in this file on a ZCML
+ layer. Tests are registered using
+ `zope.testing.doctest.DocFileSuite`.
+
+- ``:functional-zcml-layer: <ZCML_filename>``
+
+ Use the given ZCML file and run tests in this file registered with
+ `zope.app.testing.functional.DocFileSuite`.
+
+Markers are case-insensitive.
+
+See further below for explanations of the respective markers.
+
+
+Setting up a unittest 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.
Overall, use of layers is the recommended way from now on.
-
-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``)::
@@ -613,8 +609,8 @@
`testrunner layers API
<http://apidoc.zope.org/++apidoc++/Code/zope/testing/testrunner-layers-api.txt/index.html>`_.
-Specifying a ZCML file
-----------------------
+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
@@ -660,8 +656,8 @@
using ``:layer:`` and remove the ``:zcml-layer:`` marker.
-Setting up a functional ZCML layer
-----------------------------------
+Setting up a functional ZCML layer: ``:functional-zcml-layer:``
+---------------------------------------------------------------
Sometimes we want tests to be registered using the
``FunctionalDocFileSuite`` function from
@@ -708,9 +704,10 @@
be available when running the tests and during test setup. This
package is not fetched by default by ``z3c.testsetup``.
-Specifying ``setUp`` and ``tearDown`` methods
----------------------------------------------
+Specifying test setup/teardown methods: ``:setup:`` and ``:teardown:``
+----------------------------------------------------------------------
+
We can specify a ``setUp(test)`` and ``tearDown(test)`` method for the
examples in a doctest file, which will be executed once for the whole
doctest file. This can be done using::
@@ -720,7 +717,8 @@
The callables denoted by the dotted names must accept a ``test``
parameter which will be the whole test suite of examples in the
-current doctest file.
+current doctest file. setup/teardown can be used to set up (and remove) a
+temporary directory, to monkeypatch a mailer, etcetera.
An example can be found in ``doctest05.txt``::
More information about the checkins
mailing list