[Checkins] SVN: z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt Update docs.
Uli Fouquet
uli at gnufix.de
Wed Jan 7 08:55:11 EST 2009
Log message for revision 94578:
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-07 13:54:36 UTC (rev 94577)
+++ z3c.testsetup/branches/new_markers/src/z3c/testsetup/README2.txt 2009-01-07 13:55:10 UTC (rev 94578)
@@ -5,8 +5,14 @@
Setting up tests for Zope 3 projects sometimes tends to be
cumbersome. ``z3c.testsetup`` jumps in here, to support much flatter
-test setups.
+test setups. The package supports normal Python `unit tests
+<http://docs.python.org/library/unittest.html>`_ and
+`doctests <http://docs.python.org/library/doctest.html>`_.
+Note, that if you want integration or functional tests, that you have
+to make sure, that the ``zope.app.testing`` package is available
+during test runs. ``z3c.testsetup`` does **not** depend on it.
+
The package works in two steps:
1) It looks for testfiles in a given package.
@@ -21,7 +27,12 @@
using the old ':Test-Layer:' marker. It is more powerful and less
magic.
+This is a general introduction to ``z3c.testsetup``. For setup
+examples you might see the ``othercave`` package contained in the
+`tests/` directory. More details on special topics can be found in the
+appropriate .txt files in this directory.
+
Basic Example
=============
@@ -58,6 +69,47 @@
This is the only difference to 'normal' doctests here.
+Other markers detected by ``z3c.testsetup`` are:
+
+ - ``: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.
+
+ - ``: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`.
+
+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 comment (two
+ leading dots followed by whitespace) like this::
+
+ .. :doctest:
+
+ and will still work. This way you can make the markers disappear
+ from autogenerated docs etc. Markers are case-insensitive. If you
+ want to disable a test, just turn ``:doctest:`` into ``:nodoctest:``
+ and the file will be ignored.
+
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.
@@ -112,9 +164,9 @@
Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
Custom setUp for <DocTest doctest05.txt from ... (2 examples)>
Custom tearDown for <DocTest doctest05.txt from ... (2 examples)>
- Ran 6 tests with 0 failures and 0 errors in N.NNN seconds.
+ Ran 7 tests with 0 failures and 0 errors in N.NNN seconds.
Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
- Total: 11 tests, 0 failures, 0 errors in N.NNN seconds.
+ Total: 12 tests, 0 failures, 0 errors in N.NNN seconds.
False
As we can see, there were regular unittests as well as functional
@@ -125,8 +177,9 @@
Of course, there were more tests than only the ones defined in
``doctest01.txt``. Let's have a look at the other stuff.
+
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
@@ -181,8 +234,220 @@
from the very same file if you want to use them.
+
+``register_all_tests()``
+========================
+
+The `register_all_tests` function mentioned above accepts a bunch of
+keyword parameters::
+
+ register_all_tests(pkg_or_dotted_name [, extensions] [, encoding]
+ [, checker] [, globs] [, optionflags]
+ [, setup] [, teardown]
+ [, zcml_config] [, layer_name] [, layer])
+
+where all but the first parameter are keyword paramters and all but
+the package parameter are optional.
+
+While the `extensions` parameter determines the set of testfiles to be
+found, the other paramters tell how to setup single tests.
+
+The last five parameters are only fallbacks, that should better be
+configured in doctest files themselves via marker strings.
+
+- **extensions**:
+
+ a list of filename extensions to be considered during doctest
+ search. Default value for doctests is `['.txt', '.rst',
+ '.py']`. Python tests are not touched by this (they have to be
+ regular Python modules with '.py' extension).
+
+ If we want to register .foo files, we can do so::
+
+ >>> import z3c.testsetup
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... extensions=['.foo'])
+ >>> suite = test_suite()
+ >>> get_basenames_from_suite(suite)
+ ['file1.py', 'notatest1.foo', 'notatest1.foo']
+
+ Note, that only files that contain an appropriate marker are
+ found, regardless of the filename extension.
+
+
+- **encoding**:
+
+ the encoding of testfiles. 'utf-8' by default. Setting this to `None`
+ means using the default value. We've hidden one doctest file, that
+ contains umlauts. If we set the encoding to `ascii`, we get an
+ error::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... encoding='ascii')
+ >>> suite = test_suite()
+ Traceback (most recent call last):
+ ...
+ UnicodeDecodeError: 'ascii' codec can't decode ...: ordinal
+ not in range(128)
+
+ While using 'latin-1' will work::
+
+ >>> test_suite = z3c.testsetup.register_all_tests(
+ ... 'z3c.testsetup.tests.cave',
+ ... encoding='latin-1')
+ >>> suite = test_suite()
+
+ No traceback here.
+
+ You can always overwrite an encoding setting for a certain file by
+ following PEP 0263 ( http://www.python.org/dev/peps/pep-0263/ ).
+
+
+- **checker**:
+
+ An output checker for doctests. `None` by default. A typical
+ output checker can be created like this::
+
+ >>> import re
+ >>> from zope.testing import renormalizing
+ >>> mychecker = renormalizing.RENormalizing([
+ ... (re.compile('[0-9]*[.][0-9]* seconds'),
+ ... '<SOME NUMBER OF> seconds'),
+ ... (re.compile('at 0x[0-9a-f]+'), 'at <SOME ADDRESS>'),
+ ... ])
+
+ This would match for example output like `0.123 seconds` if you
+ write in your doctest::
+
+ <SOME NUBMER OF> seconds
+
+ Please see ``testrunner.txt`` for examples of usage.
+
+ Checkers are applied to functional doctests only!
+
+
+- **globs**:
+
+ A dictionary of things that should be available immediately
+ (without imports) during tests. Default is an empty dict, which
+ might be populated by appropriate layers (see below). ZCML layers
+ for example get you the ``getRootFolder`` method automatically.
+
+ 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.
+
+
+- **optionflags**:
+
+ Optionflags influence the behaviour of the testrunner. They are
+ logically or'd so that you can add them arithmetically. See
+
+ http://svn.zope.org/zope.testing/trunk/src/zope/testing/doctest.py
+
+ for details.
+
+
+- **setup**:
+
+ A callable that takes a `test` argument and is executed before
+ every single doctest.
+
+ The default function does nothing.
+
+ This parameter is a fallback which can be overriden by testfile
+ markers specifying a certain layer (see below).
+
+ Specifying setup functions in a layer is also the recommended way.
+
+
+- **teardown**:
+
+ The equivalent to `setup`.
+
+ The default function runs
+
+ zope.testing.cleanup.cleanUp()
+
+ unless overriden by a layer.
+
+ Specifying teardown functions in a layer is also the recommended
+ way.
+
+
+- **zcml_config**:
+
+ A filepath of a ZCML file which is registered with functional
+ doctests. In the ZCML file you can for example register principals
+ (users) usable by functional doctests.
+
+ By default any `ftesting.zcml` file from the root of the given
+ package is taken. If this does not exist, an empty ZCML file of
+ the z3c.testsetup package is used (``ftesting.zcml``).
+
+ This parameter has no effect, if also a ``layer`` parameter is
+ given or a docfile specifies its own layer/ZCML config (see below).
+
+ This is a fallback parameter. Use of docfile specific layer markers
+ is recommended.
+
+
+- **layer_name**:
+
+ You can name your layer, to distinguish different setups of
+ functional doctests. The layer name can be an arbitrary string.
+
+ This parameter has no effect, if also a ``layer`` parameter is
+ given or a docfile specifies its own layer/ZCML config (see
+ below).
+
+ This is a fallback parameter. Use of docfile specific layer
+ markers is recommended.
+
+- **layer**:
+
+ You can register a ZCML layer yourself and pass it as the
+ ``layer`` parameter. If you only have a filepath to the according
+ ZCML file, use the ``zcml_config`` paramter instead.
+
+ This parameter overrides any ``zcml_config`` and ``layer_name``
+ parameter.
+
+ This is a fallback parameter and has no effect for docfiles
+ specifying their own layer or ZCML config.
+
+
+Deprectated/unsupported parameters
+----------------------------------
+
+The following ``register_all_tests``-parameters are deprecated,
+starting with ``z3c.testsetup`` 0.3:
+
+- **filter_func**
+
+ and related (``ufilter_func``, ``pfilter_func``, etc.)
+
+- All testtype specific parameters
+
+ Support for testfile specific parameters (``uextensions``,
+ ``fextensions``, etc.) is running out and its use deprecated.
+
+
+Layers and setup/teardown functions
+===================================
+
+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
@@ -293,7 +558,7 @@
<http://apidoc.zope.org/++apidoc++/Code/zope/testing/testrunner-layers-api.txt/index.html>`_.
Specifying a ZCML file
-======================
+----------------------
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
@@ -340,7 +605,7 @@
Setting up a functional ZCML layer
-==================================
+----------------------------------
Sometimes we want tests to be registered using the
``FunctionalDocFileSuite`` function from
@@ -384,7 +649,7 @@
package is not fetched by default by ``z3c.testsetup``.
Specifying ``setUp`` and ``tearDown`` methods
-=============================================
+---------------------------------------------
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
More information about the Checkins
mailing list