Metadata-Version: 1.0
Name: z3c.testsetup
Version: 0.4
Summary: Easier test setup for Zope 3 projects and other Python packages.
Home-page: http://pypi.python.org/pypi/z3c.testsetup
Author: Uli Fouquet and the Zope Community
Author-email: uli@gnufix.de
License: ZPL 2.1
Description: 
        z3c.testsetup
        *************
        
        is a package that provides some convenience stuff to enable rapid test
        setup for Zope 3 components and normal Python packages. Currently
        doctests (normal unit doctests and functional doctests) and usual
        Python tests made of ``unittest.TestCase`` definitions are supported.
        
        Doctests and test modules are found throughout a whole package and
        registered with sensible, modifiable defaults.
        
        Also support for reusable test setups is provided by so-called
        TestGetters and TestCollectors.
        
        .. contents::
        
        Setting up doctests (contrary to *writing* those tests) can become
        cumbersome with Zope 3. In the environment you often have to prepare
        complex things like test layers, setup functions, teardown functions
        and much more. Often this steps have to be done again and again.
        
        ``z3c.testsetup`` can shorten this work by setting sensible defaults
        for the most important aspects of test setups.
        
        See `README.txt` in the src/z3c/testsetup directory for API
        documentation. There is also extensive documentation for (hopefully)
        every aspect of the package in this directory. See all the .txt files
        to learn more.
        
        Note, that this is alphaware! Do not use it in productive
        environments!
        
        **Important Note:**
        
        This version of ``z3c.testsetup`` uses a new set of testfile markers
        than previous releases did. If you are still using `Test-Layer:
        unit` or similar, please read the README.txt in the source directory
        carefully to learn how to switch to the new names.
        
        
        Prerequisites
        =============
        
        You need::
        
        - Python 2.4. Rumors are, that also Python 2.5 will do.
        
        - `setuptools`, available from
        http://peak.telecommunity.com/DevCenter/setuptools
        
        Other needed packages will be downloaded during
        installation. Therefore you need an internet connection during
        installation.
        
        
        Installation
        ============
        
        From the root of the package run::
        
        $ python2.4 bootstrap/bootstrap.py
        
        This will download and install everything to run `buildout` in the
        next step. Afterwards an executable script `buildout` should be
        available in the freshly created `bin/` directory.
        
        Next, fetch all needed packages, install them and create provided
        scripts::
        
        $ bin/buildout
        
        This should create a `test` script in `bin/`.
        
        Running::
        
        $ bin/test
        
        you can test the installed package.
        
        
        Usage
        =====
        
        See `README.txt` and the other .txt files in the src/z3c/testsetup
        directory for API documentation.
        
        **Note:** ``z3c.testsetup`` does **not** fetch all packages you might
        need to run your tests automatically by default. Namely the
        ``zope.app.testing`` and ``zope.component`` packages are not
        included if you require only z3c.testsetup in your `setup.py`.
        
        This is, to make ``z3c.testsetup`` compatible with packages that
        refuse collaboration when those packages are installed. For
        instance including ``zope.component`` in the dependencies would
        exclude Plone developers from using ``z3c.testsetup``.
        
        Therefore you must include ``zope.component`` and
        ``zope.app.testing`` to your ``requires`` list in `setup.py` if you
        want to use Zope 3 tests. This, however, is done anyway by other
        packages used in Zope 3 projects and in most cases you do not have
        to care about this matter.
        
        
        
        Detailed Documentation
        **********************
        
        Easy testsetups for Zope 3 and Python projects.
        
        Setting up tests for Zope 3 projects sometimes tends to be
        cumbersome. ``z3c.testsetup`` jumps in here, to support much flatter
        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.
        
        2) It registers the tests according to your specifications.
        
        .. note: Important note for users of ':Test-Layer:':
        
        The marker strings of `z3c.testsetup` changed!
        
        Please switch to the new syntax described below, if you are still
        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
        =============
        
        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::
        
        >>> 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
        ignore the pipes on the left)::
        
        >>> print_file(os.path.join(cavepath, 'doctest01.txt'))
        |  A doctest
        |  =========
        |
        |  :doctest:
        |
        |  This is a simple doctest.
        |
        |    >>> 1+1
        |    2
        |
        
        
        As we can see, the doctest is marked by a special marker
        
        `:doctest:`.
        
        This marker tells the testsetup machinery, that this file contains
        doctest examples that should be registered during test runs. Without
        this marker, a testfile won't be registered during tests!
        
        This is the only difference to 'normal' doctests here.
        
        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.
        
        - ``: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.
        
        We have such a simple testsetup already available::
        
        >>> print open(os.path.join(cavepath, 'simplesetup01.py')).read()
        import z3c.testsetup
        test_suite = z3c.testsetup.register_all_tests(
        '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.
        
        Let's start the testrunner and see what it gives::
        
        >>> import sys
        >>> sys.argv = [sys.argv[0],]
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^simplesetup01$',
        ...     ]
        >>> from z3c.testsetup import testrunner
        >>> testrunner.run(defaults)
        Running z3c...layer.DefaultZCMLLayer [...ftesting.zcml] tests:
        Set up z3c...DefaultZCMLLayer [...ftesting.zcml] in N.NNN seconds.
        Ran 3 tests with 0 failures and 0 errors in N.NNN seconds.
        Running z3c...layer.DefaultZCMLLayer [...ftesting2.zcml] tests:
        Tear down z3c...DefaultZCMLLayer [...ftesting.zcml] ... not supported
        Running in a subprocess.
        Set up z3c...DefaultZCMLLayer [...ftesting2.zcml] in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down z3c...DefaultZCMLLayer [...ftesting2.zcml] ... not supported
        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.
        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 7 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests 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
        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.
        
        
        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::
        
        >>> print_file(os.path.join(cavepath, 'doctest08.py'))
        |  """
        |  Doctests in a Python module
        |  ===========================
        |
        |  We can place doctests also in Python modules.
        |
        |  :doctest:
        |
        |  Here the Cave class is defined::
        |
        |    >>> from z3c.testsetup.tests.othercave.doctest08 import Cave
        |    >>> Cave
        |    <class 'z3c.testsetup...doctest08.Cave'>
        |
        |  """
        |  class Cave(object):
        |      """A Cave.
        |
        |      A cave has a number::
        |
        |        >>> hasattr(Cave, 'number')
        |        True
        |
        |      """
        |      number = None
        |
        |      def __init__(self, number):
        |          """Create a Cave.
        |
        |          We have to give a number if we create a cave::
        |
        |            >>> c = Cave(12)
        |            >>> c.number
        |            12
        |
        |          """
        |          self.number = number
        |
        
        Here we placed the marker string ``:doctest:`` into the docstring of
        the module. Without it, the module would not have been considered a
        testfile.
        
        Note that you have to import the entities (classes, functions, etc.)
        from the very same file if you want to use them.
        
        
        Registering regular unittests from Python modules
        -------------------------------------------------
        
        ``z3c.testsetup`` provides also (limited) support for regular
        `unittest` deployments as usually written in Python. An example file
        could look like this::
        
        >>> print_file(os.path.join(cavepath, 'pythontest1.py'))
        |  """
        |  Tests with real TestCase objects.
        |
        |  :unittest:
        |
        |  """
        |
        |  import unittest
        |
        |  class TestTest(unittest.TestCase):
        |
        |      def setUp(self):
        |          pass
        |
        |      def testFoo(self):
        |          self.assertEqual(2, 1+1)
        |
        |
        
        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.
        
        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.
        
        The only advantage of using ``z3c.testsetup`` here is, that those
        tests are found and run automatically when they provide the marker.
        
        
        ``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
        ``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: <DOTTED_NAME_OF_LAYER_DEF>`
        
        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>`_.
        
        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
        that using the
        
        `:zcml-layer: <ZCML-file-name>`
        
        marker. It expects a ZCML filename as argument and sets up a
        ZCML-layered testsuite for us. An example setup might look like so (see
        ``tests/othercave/doctest03.txt``)::
        
        A doctest with a ZCML-layer
        ===========================
        
        :doctest:
        :zcml-layer: ftesting.zcml
        
        >>> 1+1
        2
        
        .. note:: Requires ``zope.app.testing``
        
        If you use ``:zcml-layer``, the ``zope.app.testing`` package must
        be available when running the tests and during test setup. This
        package is not fetched by default by ``z3c.testsetup``.
        
        Here we say, that the the local file ``ftesting.zcml`` should be used
        as ZCML configuration. As we can see in the above output of testruner,
        this file is indeed read during test runs and used by a ZCML layer
        called ``DefaultZCMLLayer``. This layer is in fact only a
        ``zope.app.testing.functional.ZCMLLayer``.
        
        The ZCML file is looked up in the same directory as the doctest file.
        
        When using the ``:zcml-layer:`` marker, the concerned tests are set up
        via special methods and functions from `zope.app.testing`. This way
        you get 'functional' or 'integration' tests out of the box: in the
        beginning an empty ZODB db is setup, ``getRootFolder``, ``sync`` and
        other functions are pulled into the test namespace and several things
        more.
        
        If you want a plain setup instead then use your own layer definition
        using ``:layer:`` and remove the ``:zcml-layer:`` marker.
        
        
        Setting up a functional ZCML layer
        ----------------------------------
        
        Sometimes we want tests to be registered using the
        ``FunctionalDocFileSuite`` function from
        ``zope.app.testing.functional`` (other tests are set up using
        ``zope.testing.doctest.DocFileSuite``). This function pulls in even
        more functions into ``globs``, like ``http`` (a ``HTTPCaller``
        instance), wraps your ``setUp`` and ``tearDown`` methods into
        ZODB-setups and several things more. See the definition in
        http://svn.zope.org/zope.app.testing/trunk/src/zope/app/testing/functional.py?view=auto.
        
        This setup needs also a ZCML configuration file, which can be
        specified via::
        
        :functional-zcml-layer: <ZCML-file-name>
        
        If a functional ZCML layer is specified in a testfile this way, it
        will override any simple ``:zcml-layer:`` or ``:layer:`` definition.
        
        An example setup might look like this (see
        ``tests/othercave/doctest04.txt``)::
        
        >>> print_file(os.path.join(cavepath, 'doctest04.txt'))
        |  A functional doctest with ZCML-layer
        |  ====================================
        |
        |  :doctest:
        |  :functional-zcml-layer: ftesting.zcml
        |
        |  We didn't define a real environment in ftesting.zcml, but in
        |  functional tests certain often needed functions should be available
        |  automatically::
        |
        |    >>> getRootFolder()
        |    <zope...folder.Folder object at 0x...>
        |
        
        The placeholder between ``zope`` and ``folder`` was used because the
        location of the Folder class changed recently. This way we cover
        setups with old packages as well as recent ones.
        
        .. note:: Requires ``zope.app.testing``
        
        If you use ``:zcml-layer``, the ``zope.app.testing`` package must
        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
        ---------------------------------------------
        
        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::
        
        :setup: <dotted.name.of.callable>
        :teardown: <dotted.name.of.callable>
        
        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.
        
        An example can be found in ``doctest05.txt``::
        
        >>> print_file(os.path.join(cavepath, 'doctest05.txt'))
        |  A doctest with custom setup/teardown functions
        |  ==============================================
        |
        |  :doctest:
        |  :setup: z3c.testsetup.tests.othercave.testing.setUp
        |  :teardown: z3c.testsetup.tests.othercave.testing.tearDown
        |
        |    >>> 1+1
        |    2
        |
        |  We make use of a function registered during custom setup::
        |
        |    >>> myfunc(2)
        |    4
        |
        
        The setup/teardown functions denoted in the example look like this::
        
        >>> print open(os.path.join(cavepath, 'testing.py'), 'rb').read()
        import os
        ...
        def setUp(test):
        print "    Custom setUp for ", test
        # We register a function that will be available during tests.
        test.globs['myfunc'] = lambda x: 2*x
        <BLANKLINE>
        def tearDown(test):
        print "    Custom tearDown for ", test
        del test.globs['myfunc'] # unregister function
        ...
        
        As we can see, there is a function ``myfunc`` pulled into the
        namespace of the doctest. We could, however, do arbitrary other things
        here, set up a relational test database or whatever.
        
        
        How to upgrade from `z3c.testsetup` < 0.3
        =========================================
        
        With the 0.3 release of `z3c.testsetup` the set of valid marker
        strings changed, introducing support for file-dependent setups,
        layers, etc.
        
        If you still mark your testfiles with the ``:Test-Layer:`` marker,
        update your testfiles as follows:
        
        - ``:Test-Layer: unit``
        
        Change to: ``:doctest:``
        
        - ``:Test-Layer: python``
        
        Change to: ``:unittest:``
        
        - ``:Test-Layer: functional``
        
        Change to: ``:functional-zcml-layer: <ZCML-FILE>``
        
        The ZCML file must explicitly be given.
        
        If you used custom setups passed to ``register_all_tests``, consider
        declaring those setup/teardown functions in the appropriate doctest
        files using ``:setup:`` and ``:teardown:``.
        
        You might also get better structured test suites when using the new
        layer markers ``:layer:``, ``:zcml-layer:`` and
        ``functional-zcml-layer:``.
        
        Try to get rid of all parameters passed to ``register_all_tests``
        except those, mentioned in ``README.txt``.
        
        
        Setup Examples
        ==============
        
        Here we discuss complete test setups for the `cave` package contained
        in the `tests` directory. We will run the `zope.testing.testrunner`
        and examine their output.
        
        Short setups
        ------------
        
        Using z3c.testsetup, we can define quite complex testsetups with only
        two lines of code::
        
        >>> import os
        >>> cavepath = os.path.join(os.path.dirname(__file__), 'tests', 'cave')
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short0.py')
        >>> print open(setupfile).read()
        import z3c.testsetup
        test_suite = z3c.testsetup.register_all_tests('z3c.testsetup.tests.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 ``cave`` package, whose name we passed in
        dotted name notation as a string. This is enough information for a
        testrunner::
        
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^samplesetup_short0$',
        ...     ]
        >>> from z3c.testsetup import testrunner
        >>> testrunner.run(defaults)
        Running z3c.testsetup.functional.doctesting.FunctionalLayer tests:
        Set up z3c...functional.doctesting.FunctionalLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Running zope.testing.testrunner.layer.UnitTests tests:
        Tear down z3c...functional.doctesting.FunctionalLayer ... not supported
        Running in a subprocess.
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Total: 4 tests, 0 failures, 0 errors in N.NNN seconds.
        False
        
        Of the four tests apparently run, there is one 'normal' python test
        and three doctests, of which two are functional doctests.
        
        Now, we only want to run the doctests in the ``cave`` package. A
        suitable setup is contained in `samplesetup_short1.py`` in the
        ``cave`` package::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short1.py')
        >>> print open(setupfile).read()
        import z3c.testsetup
        <BLANKLINE>
        test_suite = z3c.testsetup.register_doctests('z3c.testsetup.tests.cave')
        
        This means, that we want to register all doctests from the ``cave``
        package, whose name we passed in dotted name notation as a
        string. This is enough information for a testrunner::
        
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^samplesetup_short1$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup.functional.doctesting.FunctionalLayer tests:
        Set up z3c.testsetup...doctesting.FunctionalLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Running zope.testing.testrunner.layer.UnitTests tests:
        Tear down z3c.testsetup...doctesting.FunctionalLayer ... not supported
        Running in a subprocess.
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Total: 3 tests, 0 failures, 0 errors in N.NNN seconds.
        False
        
        In the above setup the handled package was given as a string with
        dotted name notation. We can instead also pass the package itself, if
        it was loaded before. This results in a slight longer example::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short2.py')
        >>> print open(setupfile).read()
        import z3c.testsetup
        from z3c.testsetup.tests import cave
        <BLANKLINE>
        test_suite = z3c.testsetup.register_doctests(cave)
        
        
        Here we register all doctests from the ``cave`` module. Let's start a
        testrunner with this setup::
        
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^samplesetup_short2$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup.functional.doctesting.FunctionalLayer tests:
        Set up z3c.testsetup...doctesting.FunctionalLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Running zope.testing.testrunner.layer.UnitTests tests:
        Tear down z3c.testsetup...doctesting.FunctionalLayer ... not supported
        Running in a subprocess.
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Total: 3 tests, 0 failures, 0 errors in N.NNN seconds.
        False
        
        Now let's run a suite of 'normal' python unit tests, i.e. tests, that
        are not doctests. An appropriate setup file might look like this::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short3.py')
        >>> print open(setupfile).read()
        import z3c.testsetup
        from z3c.testsetup.tests import cave
        <BLANKLINE>
        test_suite = z3c.testsetup.register_pytests(cave)
        
        The only difference to the example before is, that we use
        `register_pytests` instead of `register_doctests`. If we run this
        setup with the testrunner, one test should be found and executed. This
        time we pass the `-vv` option to the testrunner, to get some more
        information from the run::
        
        >>> defaults = [
        ...     '--path', cavepath, '-vv',
        ...     '--tests-pattern', '^samplesetup_short3$',
        ...     ]
        >>> testrunner.run(defaults)
        Running tests at level 1
        Running zope.testing.testrunner.layer.UnitTests tests:
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Running:
        testFoo (z3c.testsetup.tests.cave.file1.TestTest)
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tearing down left over layers:
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        False
        
        
        Modified short setups
        ---------------------
        
        The default settings of test setups might serve for plain testing
        environments. Especially for functional tests, however, one often want
        to set some basic values not foreseeable by default. Here some hints,
        how default settings can be tweaked.
        
        Setting ZCML config file for functional tests
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Functional tests often require ZCML registration of components to make
        sense. For example one wants to register permissions etc. for use with
        a testbrowser. In other words: often one wants to register a custom
        ZCML layer when running functional doctests. This can be archieved as
        follows:
        
        We wrote a (more or less empty) ZCML config file in the ``cave``
        package, which we want to be registered with functional doctests. To
        do that, we use the now well-known ``register_all_tests`` function,
        but give a ZCML file path and a layer name as arguments::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short4.py')
        >>> print open(setupfile).read()
        import z3c.testsetup
        test_suite = z3c.testsetup.register_all_tests(
        'z3c.testsetup.tests.cave',
        zcml_config='sampleftesting.zcml',
        layer_name = 'SampleLayer')
        
        This will result in::
        
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^samplesetup_short4$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup.tests.cave.SampleLayer tests:
        Set up z3c.testsetup.tests.cave.SampleLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Running zope.testing.testrunner.layer.UnitTests tests:
        Tear down z3c.testsetup.tests.cave.SampleLayer ... not supported
        Running in a subprocess.
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Total: 4 tests, 0 failures, 0 errors in N.NNN seconds.
        False
        
        Apparently now the custom ZCML file in the ``cave`` package was used.
        
        
        Setting output checker for functional tests
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Output checkers modify the way, output of tests is recognized. This is
        important for output which can not be foreseen exactly, timestamps for
        example, or local file paths. In this case sometimes a regular
        expression would match every single expression, but how can I tell the
        testrunner, that all timestamps of the form 'N.NNN seconds' are
        acceptable? Easy: use a checker::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short5.py')
        >>> print open(setupfile).read()
        import re
        from zope.testing import renormalizing
        import z3c.testsetup
        mychecker = renormalizing.RENormalizing([
        (re.compile('[0-9]*[.][0-9]* seconds'),
        '<SOME NUMBER OF> seconds'),
        (re.compile('at 0x[0-9a-f]+'), 'at <SOME ADDRESS>'),
        ])
        test_suite = z3c.testsetup.register_all_tests(
        'z3c.testsetup.tests.cave',
        checker = mychecker,
        extensions = ['.chk',],
        fregexp_list = ['.*checker.*',],
        )
        
        This setup will find exactly one testfile, the file
        ``checkertest.chk`` in the ``cave`` package, that checks for output of
        the form 'N.NNN seconds', with an arbitrary number of numbers.
        
        Running the testrunner with this setup will result in::
        
        >>> defaults = [
        ...     '--path', cavepath, '-f',
        ...     '--tests-pattern', '^samplesetup_short5$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup....doctesting.FunctionalLayer tests:
        Set up z3c.testsetup....doctesting.FunctionalLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Tearing down left over layers:
        Tear down z3c.testsetup....doctesting.FunctionalLayer ... not supported
        False
        
        The same setup, but without a modified checker will deliver::
        
        >>> defaults = [
        ...     '--path', cavepath, '-f',
        ...     '--tests-pattern', '^samplesetup_short6$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup....doctesting.FunctionalLayer tests:
        Set up z3c.testsetup....doctesting.FunctionalLayer in ... seconds.
        <BLANKLINE>
        <BLANKLINE>
        Failure in test ...checkertest.chk
        Failed doctest test for checkertest.chk
        File "...checkertest.chk", line 0
        <BLANKLINE>
        ----------------------------------------------------------------------
        File "...checkertest.chk", line 10, in checkertest.chk
        Failed example:
        print "%s seconds" % 0.123
        Differences (ndiff with -expected +actual):
        - <SOME NUMBER OF> seconds
        + 0.123 seconds
        ----------------------------------------------------------------------
        File "...checkertest.chk", line 15, in checkertest.chk
        Failed example:
        print "A memory address at 0x1a0322ff"
        Differences (ndiff with -expected +actual):
        - A memory address at <SOME ADDRESS>
        + A memory address at 0x1a0322ff
        <BLANKLINE>
        Ran 2 tests with 1 failures and 0 errors in ... seconds.
        Tearing down left over layers:
        Tear down z3c.testsetup....doctesting.FunctionalLayer ... not supported
        True
        
        Note that checkers are currently only supported for functional
        doctests.
        
        
        Setting globals for doctests
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        For a testsuite you can define a set of globals, which are applied to
        each test before it runs. Normally one uses such globals, to have
        certain functions or objects available, which are complex to setup
        during tests but useful.
        
        The objects and functions registered this way can then be used by
        their names in tests out-of-the-box.
        
        You can pass the globals for a testsetup by passing the ``globs``
        keyword parameter or ``fglobs``/``uglobs``, if you only want them to
        be applied to either functional or unit doctests.
        
        If you specify a `globs` parameter and a `fglobs` or `uglobs`
        parameter, the latter will shadow the `globs` values. So `globs` will
        have no effect, if you specify also both, `fglobs` and `uglobs`.
        
        An example of the ``globs`` usage can be found in
        ``samplesetup_short7`` of the ``cave`` package::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short7.py')
        >>> print open(setupfile).read()
        import os
        from zope.testing import renormalizing
        import z3c.testsetup
        test_suite = z3c.testsetup.register_all_tests(
        'z3c.testsetup.tests.cave',
        extensions = ['.chk',],
        fregexp_list = [':Test-Layer:.*globs.*',],
        globs = {
        'basename' : os.path.basename
        }
        )
        
        Here the ``os.path.basename`` function is registered under the name
        'basename' and should be usable in the doctest file
        ``globstest.chk``::
        
        >>> defaults = [
        ...     '--path', cavepath, '-f',
        ...     '--tests-pattern', '^samplesetup_short7$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup....doctesting.FunctionalLayer tests:
        Set up z3c.testsetup....doctesting.FunctionalLayer in ... seconds.
        Ran 1 tests with 0 failures and 0 errors in ... seconds.
        Tearing down left over layers:
        Tear down z3c.testsetup....doctesting.FunctionalLayer ... not supported
        False
        
        The testrunner finished without any error. So the ``basename``
        function was indeed known to the doctest and could be used.
        
        The same should happen, if we use the ``fglobs`` argument instead of
        ``globs``::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short8.py')
        >>> print open(setupfile).read()
        import os
        ...
        test_suite = z3c.testsetup.register_all_tests(
        'z3c.testsetup.tests.cave',
        extensions = ['.chk',],
        fregexp_list = [':Test-Layer:.*globs.*',],
        fglobs = {
        'basename' : os.path.basename
        }
        )
        
        >>> defaults = [
        ...     '--path', cavepath, '-f',
        ...     '--tests-pattern', '^samplesetup_short8$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c.testsetup....doctesting.FunctionalLayer tests:
        ...
        Ran 1 tests with 0 failures and 0 errors in ... seconds.
        ...
        False
        
        Finally, we can register the same doctestfile as unit doctest, such
        making sure, that also unit doctests globals can be set, using the
        ``uglobs`` keyword parameter::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup_short9.py')
        >>> print open(setupfile).read()
        import os
        ...
        test_suite = z3c.testsetup.register_all_tests(
        'z3c.testsetup.tests.cave',
        extensions = ['.chk',],
        uregexp_list = [':Test-Layer:.*globs.*',],
        uglobs = {
        'basename' : os.path.basename
        }
        )
        
        >>> defaults = [
        ...     '--path', cavepath, '-u',
        ...     '--tests-pattern', '^samplesetup_short9$',
        ...     ]
        >>> testrunner.run(defaults)
        Running zope.testing.testrunner.layer.UnitTests tests:
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Tearing down left over layers:
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        False
        
        
        
        
        Extended setups
        ---------------
        
        Let's have a look at the test setup module `samplesetup1` in the
        `cave` package::
        
        >>> setupfile = os.path.join(cavepath, 'samplesetup1.py')
        >>> print open(setupfile).read()
        import unittest
        import z3c.testsetup
        from z3c.testsetup.tests import cave # The package that contains
        # the doctest files
        def test_suite():
        suite = unittest.TestSuite()
        suite.addTest( # Add all unittests from `cave`
        z3c.testsetup.UnitDocTestSetup(cave).getTestSuite())
        suite.addTest( # Add all functional tests from `cave`
        z3c.testsetup.FunctionalDocTestSetup(cave).getTestSuite())
        return suite
        
        
        As we see, there is a unittest setup and a functional test setup
        initialized. Both collect one kind of tests and feed their collection
        in the same testsuite (where each kind of tests is setup differently,
        of course).
        
        Now let's run a testrunner and see the result. The testrunner will be
        configured such, that all files named 'samplesetup1.py' will be asked
        to return a testsuite::
        
        >>> defaults = [
        ...     '--path', cavepath,
        ...     '--tests-pattern', '^samplesetup1$',
        ...     ]
        >>> from z3c.testsetup import testrunner
        >>> testrunner.run(defaults)
        Running z3c.testsetup.functional.doctesting.FunctionalLayer tests:
        Set up z3c.testsetup...doctesting.FunctionalLayer in N.NNN seconds.
        Ran 2 tests with 0 failures and 0 errors in N.NNN seconds.
        Running zope.testing.testrunner.layer.UnitTests tests:
        Tear down z3c.testsetup...doctesting.FunctionalLayer ... not supported
        Running in a subprocess.
        Set up zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down zope.testing.testrunner.layer.UnitTests in N.NNN seconds.
        Total: 3 tests, 0 failures, 0 errors in N.NNN seconds.
        False
        
        We ran one unittest and two functional tests.
        
        
        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
        two 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')
        
        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>
        :Test-Layer: unit
        :Test-Layerdef: z3c.testsetup.tests.layered_cave.layer.UnitLayer1
        ...
        
        The line saying `:Test-Layerdef:` 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::
        
        :test-layerdef: <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::
        
        >>> defaults = [
        ...     '--path', cavepath, '-f',
        ...     '--tests-pattern', '^layeredsetup01$',
        ...     ]
        >>> testrunner.run(defaults)
        Running z3c...DefaultZCMLLayer [/.../bar/ftesting.zcml] tests:
        Set up z3c...DefaultZCMLLayer [/.../bar/ftesting.zcml] in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Running z3c...DefaultZCMLLayer [/.../foo/ftesting.zcml] tests:
        Tear down z3c...efaultZCMLLayer [/.../bar/ftesting.zcml] ... not supported
        Running in a subprocess.
        Set up z3c...efaultZCMLLayer [/.../foo/ftesting.zcml] in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down z3c...efaultZCMLLayer [/.../foo/ftesting.zcml] ... not supported
        Running z3c.testsetup.tests.layered_cave.layer.FunctionalLayer1 tests:
        Running in a subprocess.
        Set up z3c...layered_cave.layer.FunctionalLayer1 in N.NNN seconds.
        Ran 1 tests with 0 failures and 0 errors in N.NNN seconds.
        Tear down z3c...layered_cave.layer.FunctionalLayer1 in N.NNN seconds.
        Running z3c.testsetup.tests.layered_cave.layer.UnitLayer1 tests:
        Running in a subprocess.
        Set up z3c.testsetup.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...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.
        
        Convenience Stuff
        =================
        
        Here we collect some convenience stuff, that might be useful for
        testers. Most people, however, won't need them.
        
        ``z3c.testsetup.testrunner``
        ----------------------------
        
        With `zope.testing`_ 3.7.3 the behaviour of
        `zope.testing.testrunner.run()` changed and now exits always with
        status. See http://svn.zope.org/zope.testing/?rev=99366&view=rev
        
        To run testrunners as part of tests, one now has to use
        `testrunner.run_internal()` instead of `testrunner.run()`. This makes
        it hard to test with packages, that sometimes use `zope.testing`_
        >= 3.7.3 but are also used with `zope.testing`_ < 3.7.3.
        
        For those cases (i.e. where testrunners are run as part of tests
        themselves) `z3c.testsetup` now offers the convenience functions
        `testrunner.run()` and `testrunner.run_internal()` that are wrappers
        guaranteed to be aliases for the same function of `zope.testing`:
        ``zope.testing.testrunner.run_internal()`` if it exists or
        ``zope.testing.testrunner.run()`` otherwise.
        
        In doctests you now can use
        
        >>> from z3c.testsetup import testrunner
        
        call ``testrunner.run()`` afterwards and it will work, regardless of
        what version of `zope.testing` you are using.
        
        This is only interesting for people that run tests, which itself run
        testrunners (like `z3c.testsetup` itself in self-tests).
        
        The functions provided by the faked testrunners of z3c.testsetup refer
        to the same thing:
        
        >>> from z3c.testsetup import testrunner
        >>> testrunner.run is testrunner.run_internal
        True
        
        If `zope.testing`_ >= 3.7.3 is running in background, both functions
        refer to `zope.testing.testrunner.run_internal`:
        
        >>> import pkg_resources
        >>> info = pkg_resources.get_distribution('zope.testing')
        >>> version = tuple(info.version.split('.'))
        >>> new_version = (version > ('3', '7', '2'))
        
        >>> from zope.testing.testrunner import run
        >>> not new_version or (testrunner.run is not run)
        True
        
        Otherwise both functions refer to `zope.testing.testrunner.run()`:
        
        >>> (run is testrunner.run_internal) or new_version
        True
        
        .. _`zope.testing`: http://pypi.python.org/pypi/zope.testing
        
        
        CHANGES
        *******
        
        0.4 (2009-06-11)
        ================
        
        Bug fixes
        ---------
        
        * Made ``z3c.testsetup`` selftests work with ``zope.testing`` >=
        3.7.3. Thanks to Jonathan Ballet for pointing to that problem.
        
        * Ignore \*nix hidden test files (i.e. such starting with a dot in
        filename) by default. Thanks to Jonathan Ballet for patch.
        
        * ZCML files registered via the default layer are now separated from
        each other, even if they own the same filename. Therefore you can now
        register a default layer with an ``ftesting.zcml`` in one subpackage
        while having another ``ftesting.zcml`` in another package. This was
        not handled correctly before. Many thanks go to Jonathan Ballet who
        contributed a patch.
        
        Feature Changes
        ---------------
        
        * Added ``z3c.testsetup.testrunner`` that provides wrappers for
        ``zope.testing.testrunner``s ``run()`` and ``run_internal()``
        functions. Using it, one can make sure that running testrunners
        inside tests will work regardless of which version of
        ``zope.testing`` is used during testruns.
        
        0.3 (2009-02-23)
        ================
        
        Bug fixes
        ---------
        
        * Updated doctest examples to reflect new ``zope.testing`` behaviour.
        
        * ``z3c.testsetup`` really shouldn't require ``zope.app.testing`` any
        more. If you use it in an environment without this package, then you
        cannot register functional tests, which is determined when loading
        ``register_all_tests`` from ``z3c.testsetup``.
        
        * Broken modules are ignored while scanning for tests.
        
        * Modules are not loaded anymore if their source code does not provide
        a suitable marker string. For this to work, the default checker
        method ``isTestModule`` now expects a ``martian.scan.ModuleInfo`` as
        argument and not a real module. Module infos can be easily created
        by using ``module_info_from_dotted_name`` and
        ``module_info_from_package`` from the ``martian.scan`` package.
        
        Feature Changes
        ---------------
        
        * New set of testfile markers:
        
        - `:doctest:`
        
        marks a testfile as a doctest.
        
        - `:unittest:`
        
        marks a testfile as a regular unittest.
        
        - `:layer: dotted.name.to.layer.def`
        
        applies the given layer definition to the tests in the doctest
        file.
        
        - `:zcml-layer: filename.zcml`
        
        sets up a ZCML layer with the given filename and applies this
        layer to the doctests in the doctest file.
        
        - `:functional-zcml-layer: filename.zcml`
        
        sets up a ZCML layer with the given filename and applies this
        layer to the doctests in the doctest file. Furthermore the tests
        are set up as functional doc tests.
        
        - `:setup: dotted.name.to.setup.function`
        
        applies the setUp function denoted by the dotted name to the tests
        in the doctest file.
        
        - `:teardown: dotted.name.to.teardown.function`
        
        applies the tearDown function denoted by the dotted name to the
        tests in the doctests file.
        
        See the examples in `tests/othercave` and README.txt to learn more
        about using these new directives.
        
        The old `:test-layer:` marker is still supported but it is
        deprecated now and will vanish at least with the 0.5 version of
        `z3c.testsetup`.
        
        
        0.2.2 (2008-02-29)
        ==================
        
        Bug fixes
        ---------
        
        * ``z3c.testsetup`` now does not require ``zope.component`` nor
        ``zope.app.testing`` for usage in other packages. You must take
        care, that those packages are available during tests, for example by
        adding those packages to your `setup.py`.
        
        0.2.1 (2008-02-18)
        ==================
        
        Bug fixes
        ---------
        
        * Fix faulty upload egg.
        
        
        0.2 (2008-02-17)
        ================
        
        Feature Changes
        ---------------
        
        * An `ftesting.zcml` in the root of a handled package is now taken as
        default layer for functional doctests if it exists.
        
        Bug fixes
        ---------
        
        
        0.1 (2008-02-15)
        ================
        
        Feature changes
        ---------------
        
        - Initial Release
        
        
        Download
        ********
        
Keywords: zope3 zope tests unittest doctest testsetup
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Framework :: Zope3
