[Checkins] SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/ Copy tests from grok trunk.

Uli Fouquet uli at gnufix.de
Thu Jan 31 19:41:50 EST 2008


Log message for revision 83367:
  Copy tests from grok trunk.

Changed:
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/basicsetup.py
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/functionalsetup.py
  A   Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/unittestsetup.py

-=-
Copied: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/basicsetup.py (from rev 83366, grok/trunk/src/grok/tests/testsetup/basicsetup.py)
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/basicsetup.py	                        (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/basicsetup.py	2008-02-01 00:41:50 UTC (rev 83367)
@@ -0,0 +1,258 @@
+##############################################################################
+#
+# Copyright (c) 2007 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""
+================
+Basic Test Setup
+================
+
+``BasicTestSetup`` is a class to support easier setup of tests in grok
+projects. It acts merely as a container for shared functions, methods
+and attributes needed by 'real' test setups which are derived from
+it. Itself provides *no* ``getTestSuite()`` method, which is needed to
+setup real tests.
+
+A ``BasicTestSetup`` tries to find all doctest files defined in a given
+package. See `functionalsetup.py` for setting up real functional tests
+and `unittestsetup.py` for 'real' setup of unittests.
+
+For a general introduction into testing with grok see the appropriate
+howto on the grok homepage.
+
+The TestSetup classes all search and handle doctest files.
+
+All we need to setup a testsuite, is the package to search::
+
+   >>> from grok.tests.testsetup import cave
+   >>> from grok.testing import BasicTestSetup
+   >>> basic_setup = BasicTestSetup(cave)
+   >>> basic_setup
+   <grok.testing.BasicTestSetup object at 0x...>
+
+The package is stored as an instance-attribute::
+
+   >>> basic_setup.package
+   <module 'grok.tests.testsetup.cave' from ...>
+
+The ``BasicTestSetup`` serves merely as a container for attributes and
+methods needed by derived classes, that provide proper test setup.
+
+One of it's resposibilities is, to find doctest files, which is done
+by the ``getDocTestFiles()`` method. If we run this method, we
+get a list of filenames::
+
+   >>> file_list = basic_setup.getDocTestFiles()
+   >>> len(file_list)
+   4
+
+The filenames are all absolute::
+
+   >>> import os.path
+   >>> [x for x in file_list if not os.path.isabs(file_list[0])]
+   []
+
+
+Which files are found?
+----------------------
+
+By default, all .txt and .rst files are taken
+into account::
+
+   >>> exts = ['.rst', '.txt']
+   >>> [x for x in file_list if not os.path.splitext(x)[1].lower() in exts]
+   []
+
+All forms of an extension are found, regardless of whether they are
+uppercase, lowercase or mixed-case::
+
+   >>> file_list
+   [...'...file2.TXT'...]
+
+Also subdirectories are searched::
+
+   >>> file_list
+   [...'...subdirfile.txt'...]
+
+Hidden directories, however, are skipped. To check this, we look for a
+'hidden' testfile put into a hidden directory in the `cave`
+directory. We first make sure, that the hidden file really exists::
+
+   >>> cavepath = os.path.dirname(cave.__file__)
+   >>> hiddenpath = os.path.join(cavepath, '.hiddendir', 'hiddenfile.txt')
+   >>> os.path.exists(hiddenpath)
+   True
+
+And now check that it was *not* included in the file list::
+
+   >>> hiddenpath in file_list
+   False
+
+To provide a more finegrained filtering, ``BasicTestSetup`` provides a
+method ``isTestFile(filepath)``, which returns ``True`` for accepted
+files and ``False`` otherwise. This method is called for every file
+found by ``getDoctesFiles``. By default it only filters files by their
+filename extension and compares it with the instance-attribute
+``extensions``, which by default is the list ``['.rst', '.txt']``::
+
+   >>> basic_setup.extensions
+   ['.rst', '.txt']
+
+   >>> basic_setup.isTestFile('')
+   False
+
+   >>> basic_setup.isTestFile('cave.txt')
+   True
+
+   >>> basic_setup.isTestFile('cave.rst')
+   True
+
+   >>> basic_setup.isTestFile('cave.RsT')
+   True
+
+   >>> basic_setup.isTestFile('cave.foo')
+   False
+
+
+How to find a customized set of files:
+--------------------------------------
+
+There are several possibilities to modify the search results of
+``getDocTestFiles()``. If it is only a matter of filename extension,
+the instance's attribute ``extensions`` can be modified::
+
+   >>> basic_setup.extensions = ['.foo']
+   >>> basic_setup.getDocTestFiles()
+   ['...notatest1.foo']
+
+If things need a more complex filtering, you can also redefine the
+filter function, which by default is the ``isTestFile()`` function as
+mentioned above.
+
+You can pass an alternative filterfunction as keyword parameter
+``filter_func`` to the ``BasicTestSetup`` constructor::
+
+   >>> def myFilter(filename):
+   ...     return filename.endswith('.txt')
+   >>> basic_setup2 = BasicTestSetup(cave, filter_func=myFilter)
+   >>> len(basic_setup2.getDocTestFiles())
+   2
+
+Note, that the filter function must accept a single parameter, which
+should contain a filepath as string and it should return a boolean
+value to indicate, whether the file given by the filepath should be
+included in the test suite or not.
+
+A different set of accepted filename extensions can also be passed to
+the constructor, using the ``extensions`` keyword::
+
+   >>> basic_setup3 = BasicTestSetup(cave, extensions=['.txt'])
+
+Note, that the extensions should alway be written with a leading dot
+and in lower case. Such we can find only .txt files::
+
+   >>> len(basic_setup3.getDocTestFiles())
+   3
+
+Now also the .TXT file was found, which was omitted in the test
+before.
+
+The set of directories, which are accepted as doctest containers, is
+defined by the ``isTestDirectory`` method, which by default only skips
+'hidden' directories, i.e. directories, that start with a dot ('.').
+
+   >>> basic_setup3.isTestDirectory('foo/bar/somdir')
+   True
+
+   >>> basic_setup3.isTestDirectory('foo/bar/.hiddendir')
+   False
+
+You can change this behaviour by deriving your own setup class and
+overwriting the method. This works also with derived classes like
+``FunctionalTestSetup``.
+
+
+Find terms in docfiles:
+-----------------------
+
+For convenience ``BasicTestSetup`` provides a method ``fileContains``,
+which parses the contents of a file to match a list of regular
+expressions. If every of the regular expressions in the list matched
+at least one line of the file, ``True`` is returned, ``False``
+otherwise.
+
+``fileContains`` is a helper function to search files for certain
+terms and expressions. It is implemented as a method (instead a
+standalone function), to enable developers to replace it with a more
+complex implementation that also accesses other instance attributes
+like the package or similar.
+
+File paths, that cannot be found, are silently ignored::
+
+   >>> basic_setup4 = BasicTestSetup(cave, extensions=['.foo'])
+   >>> basic_setup4.fileContains('blah', ['FOO'])
+   False
+
+We pick up an existing file path::
+
+   >>> file_list = basic_setup4.getDocTestFiles()
+   >>> len(file_list)
+   1
+
+   >>> filepath = file_list[0]
+   >>> filepath.endswith('notatest1.foo')
+   True
+
+This file contains a string 'ME GROK SMASH ZCML!!', which we can
+search for::
+
+   >>> basic_setup4.fileContains(filepath, ['ME GROK'])
+   True
+
+   >>> basic_setup4.fileContains(filepath, ['ME GROK IS DUMB'])
+   False
+
+The terms to search are handled as real regular expressions as
+provided by the ``re`` package::
+
+   >>> basic_setup4.fileContains(filepath, ['^ME (G|g)ROK.*'])
+   True
+
+We can also search for several matches::
+
+   >>> basic_setup4.fileContains(filepath, ['.*SMASH.*', '.*GROK.*'])
+   True
+
+If one of the searched terms is not found, the whole thing fails::
+
+   >>> basic_setup4.fileContains(filepath, ['.*DUMB.*', '.*GROK.*'])
+   False
+
+It does not matter, whether matches occur in the same line or in
+different ones. In the example file there is also a heading stating
+'This is not a test'. Let's check this::
+
+   >>> basic_setup4.fileContains(filepath, ['ME GROK', 'This is not'])
+   True
+
+
+Note: The evaluation of regular expressions is done without any
+modifiers. Namely the matching is case sensitive::
+
+   >>> basic_setup4.fileContains(filepath, ['me grok'])
+   False
+
+Furthermore, matches are only done against one line at a time.
+
+
+
+"""

Copied: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave (from rev 83366, grok/trunk/src/grok/tests/testsetup/cave)

Copied: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/functionalsetup.py (from rev 83366, grok/trunk/src/grok/tests/testsetup/functionalsetup.py)
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/functionalsetup.py	                        (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/functionalsetup.py	2008-02-01 00:41:50 UTC (rev 83367)
@@ -0,0 +1,280 @@
+##############################################################################
+#
+# Copyright (c) 2007 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""
+=====================
+Functional Test Setup
+=====================
+
+``FunctionalTestSetup`` helps to find and setup functional doctests
+contained in a package. The most important method therefore might be
+``getTestSuite()``, which searches a given package for doctest files
+and returns all tests found as a suite of functional tests.
+
+The work is done mainly in two stages:
+
+1) The package is searched for appropriate docfiles, based on the
+   settings of instcance attributes.
+
+2) The tests contained in the found docfiles are setup as functional
+   tests and added to a ``unittest.TestSuite`` instance.
+
+There are plenty of default values active, if you use instances of
+this class without further modifications. Therefore we will first
+discuss the default behaviour and afterwards show, how you can modify
+this behaviour to suit your special expectations on the tests.
+
+
+Setting up a simple test suite
+------------------------------
+
+We want to register the tests contained in the local ``cave``
+package. This has to be imported first, because we need the package as
+a parameter for the testseupt constructor::
+
+   >>> from grok.tests.testsetup import cave
+
+Using the ``FunctionalTestSetup`` then is easy::
+
+   >>> from grok.testing import FunctionalTestSetup
+   >>> setup = FunctionalTestSetup(cave)
+   >>> setup
+   <grok.testing.FunctionalTestSetup object at 0x...>   
+
+This setup is ready for use::
+
+   >>> suite = setup.getTestSuite()
+   >>> suite
+   <unittest.TestSuite tests=[...]>
+
+To sum it up, writing a test setup for a grok project now can be that
+short::
+
+   import unittest
+   import grok
+   import cave
+   def test_suite():
+       setup = grok.testing.FunctionalTestSetup(cave)
+       return setup.getTestSuite()
+   if __name__ == '__main__':
+       unittest.main(default='test_suite')
+
+This will find all .rst and .txt files in the package that provide a
+certain signature (see below), register the contained tests as
+functional tests and run them as part of a `unittest.TestSuite`.
+
+
+FunctionalTestSetup default values
+----------------------------------
+
+Understanding the defaults is important, because the default values
+are driving the whole process of finding and registering the test.
+
+
+Which files are found by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basically, all files are accepted that
+
+1) reside inside the package passed to the constructor. This includes
+   subdirectories.
+
+2) have a filename extension `.txt` or `.rst` (uppercase, lowercase
+   etc. does not matter).
+
+3) are *not* located inside a 'hidden' directory (i.e. a directory
+   starting with a dot ('.'). Also subdirectories of 'hidden'
+   directories are skipped.
+
+4) contain a ReStructured Text meta-marker somewhere, that defines the
+   file as a functional test explicitly::
+
+       :Test-Layer: functional
+
+   This means: there *must* be a line like the above one in the
+   doctest file. The term might be preceeded or followed by whitspace
+   characters (spaces, tabs).
+
+Only files, that meet all four conditions are searched for functional
+doctests. You can modify this behaviour of course, which will be
+explained below in detail.
+
+
+What options are set by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many options can be set, when registering functional doctests. When
+using the default set of options, the following values are set::
+
+* The setup-instance's ``setUp``-method is set as the ``setUp``
+  function.
+
+* The setup-instance's ``tearDown``-method is set as the ``tearDown``
+  function.
+  
+     >>> setup.setUp
+     <bound method FunctionalTestSetup.setUp of
+      <grok.testing.FunctionalTestSetup object at 0x...>>
+
+* The setup-instance's `globs` attribute is passed as the `globs`
+  parameter. By default `globs` is a dictionary of functions, that
+  should be'globally' available during testruns and it contains::
+
+     >>> setup.globs
+     {'http': <zope.app.testing.functional.HTTPCaller object at 0x...>,
+      'sync': <function sync at 0x...>,
+      'getRootFolder': <function getRootFolder at 0x...>}
+
+  The functions `sync` and `getRootFolder` are provided by
+  `zope.app.testing.functional`.
+
+* The setup-instance's `optionsflags` attribute is passed. It
+  includes by default the following doctest constants:
+
+     >>> from zope.testing import doctest
+     >>> setup.optionflags == (doctest.ELLIPSIS+
+     ...                       doctest.NORMALIZE_WHITESPACE |
+     ...                       doctest.REPORT_NDIFF)
+     True
+
+* Furthermore, additional keyword parameters are passed, which were
+  set when calling the constructor. These keywords are stored in the
+  setup object as `additional_options`. Those are empty by default::
+
+     >>> setup.additional_options
+     {}
+
+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`::
+
+   >>> setup.layer
+   <zope.app.testing.functional.ZCMLLayer instance at 0x...>
+
+   >>> setup.layer.config_file
+   '...ftesting.zcml'
+
+   
+
+No other options/parameters are set by default.
+
+
+Customizing functional test setup:
+----------------------------------
+
+You can modify the behaviour of grok.testing.FunctionalTestSetup such,
+that a different set of files is registered and/or the found tests are
+registered with a different set of parameters/options. We will first
+discuss modifying the set of files to be searched.
+
+
+Customizing the doctest file search:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The searching of appropriate doctest files is basically done by the
+base class `BasicTestSetup`. Its purpose is to determine the set of
+files in a package, that contain functional tests. See the testfile
+`basicsetup.py` to learn more about the procedure.
+
+The functional test setup, however, provides a special
+`isDocTestFile()` method, which does additional checking. Namely it
+checks for the existance of the above mentioned ReStructured Text
+meta-marker::
+
+    `:Test-Layer: functional`
+
+This is determined by a list of regular expressions, which is also
+available as an object attribute::
+
+    >>> setup.regexp_list
+    ['^\\\\s*:(T|t)est-(L|l)ayer:\\\\s*(functional)\\\\s*']
+
+This is the default value of functional test setups.
+
+There are two files in the `cave` subpackage, which include that
+marker. We can get the list of test files using
+`getDocTestFiles()``::
+
+    >>> testfile_list = setup.getDocTestFiles()
+    >>> testfile_list.sort()
+    >>> testfile_list
+    ['...file1.txt', '...subdirfile.txt']
+
+    >>> len(testfile_list)
+    2
+
+The ``isTestFile()`` method of our setup object did the filtering
+here::
+
+    >>> setup.isTestFile(testfile_list[0])
+    True
+
+The file file1.rst does not contain a functional test marker::
+
+    >>> import os.path
+    >>> path = os.path.join(os.path.dirname(cave.__file__),
+    ...                     'test1.rst')
+    >>> setup.isTestFile(path)
+    False
+
+The `regexp_list` attribute of a ``FunctionalTestSetup`` contains a
+list of regular expressions, of which each one must at least match one
+line of a searched file to be accepted. If you want to include files
+with different marker-strings, just change this attribute. The value
+will influence behaviour of the `isTestFile()``, ``getDocTestFiles()``
+and ``getTestSuite()`` methods.
+
+If you need more complex checks here, you can derive your customized
+test setup class and overwrite ``isTestFile()``.
+
+See `basicsetup.py` for further methods how to modify test file
+search, for example by choosing another set of accepted filename
+extensions.
+
+
+Customizing the functional test setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To customize the setup of your tests, just modify the appropriate
+attributes as explained before.
+
+To setup a different setUp or tearDown function, you can define a
+derived class, that overwrites these methods.
+
+A convenient way to pass keyword parameters to the test setup, which
+do not appear in the attributes, is passing these keywords (and the
+values) to the constructor::
+
+    >>> encoded_setup = FunctionalTestSetup(cave,
+    ...                                     encoding='utf-8')
+
+This will read all doctests 'utf-8' encoded, which allow umlauts and
+similar chars in tests. Note, however, that you can archieve this very
+special behaviour also by writing an appropriate encoding string in
+the head of the doctest file.
+
+All keywords passed to the constructor (except 'filter_func' and
+'extensions') are also given to each individual test setup 'as-is'.
+
+Alternatively you can also modify the `additional_options` dictionary
+of a ``FunctionalTestSetup`` object.
+
+    >>> encoded_setup.additional_options
+    {'encoding': 'utf-8'}
+
+    >>> encoded_setup.additional_options['encoding'] = 'latin1'
+
+
+
+"""

Copied: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/unittestsetup.py (from rev 83366, grok/trunk/src/grok/tests/testsetup/unittestsetup.py)
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/unittestsetup.py	                        (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/unittestsetup.py	2008-02-01 00:41:50 UTC (rev 83367)
@@ -0,0 +1,252 @@
+##############################################################################
+#
+# Copyright (c) 2007 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""
+===============
+Unit Test Setup
+===============
+
+``UnitTestSetup`` helps to find and setup unit doctests contained in a
+package. The most important method therefore might be
+``getTestSuite()``, which searches a given package for doctest files
+and returns all tests found as a suite of unit tests.
+
+The work is done mainly in two stages:
+
+1) The package is searched for appropriate docfiles, based on the
+   settings of instcance attributes.
+
+2) The tests contained in the found docfiles are setup as unit tests
+   and added to a ``unittest.TestSuite`` instance.
+
+There are plenty of default values active, if you use instances of
+this class without further modifications. Therefore we will first
+discuss the default behaviour and afterwards show, how you can modify
+this behaviour to suit your special expectations on the tests.
+
+
+Setting up a simple test suite
+------------------------------
+
+We want to register the tests contained in the local ``cave``
+package. This has to be imported first, because we need the package as
+a parameter for the testseupt constructor::
+
+   >>> from grok.tests.testsetup import cave
+
+Using the ``UnitTestSetup`` then is easy::
+
+   >>> from grok.testing import UnitTestSetup
+   >>> setup = UnitTestSetup(cave)
+   >>> setup
+   <grok.testing.UnitTestSetup object at 0x...>   
+
+This setup is ready for use::
+
+   >>> suite = setup.getTestSuite()
+   >>> suite
+   <unittest.TestSuite tests=[...]>
+
+To sum it up, writing a test setup for a grok project now can be that
+short::
+
+   import unittest
+   import grok
+   import cave
+   def test_suite():
+       setup = grok.testing.UnitTestSetup(cave)
+       return setup.getTestSuite()
+   if __name__ == '__main__':
+       unittest.main(default='test_suite')
+
+This will find all .rst and .txt files in the package that provide a
+certain signature (see below), register the contained tests as unit
+tests and run them as part of a `unittest.TestSuite`.
+
+
+UnitTestSetup default values
+----------------------------
+
+Understanding the defaults is important, because the default values
+are driving the whole process of finding and registering the test.
+
+
+Which files are found by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basically, all files are accepted that
+
+1) reside inside the package passed to the constructor. This includes
+   subdirectories.
+
+2) have a filename extension `.txt` or `.rst` (uppercase, lowercase
+   etc. does not matter).
+
+3) are *not* located inside a 'hidden' directory (i.e. a directory
+   starting with a dot ('.'). Also subdirectories of 'hidden'
+   directories are skipped.
+
+4) contain a ReStructured Text meta-marker somewhere, that defines the
+   file as a unit test (and not: functional test) explicitly::
+
+       :Test-Layer: unit
+
+   This means: there *must* be a line like the above one in the
+   doctest file. The term might be preceeded or followed by whitspace
+   characters (spaces, tabs).
+
+Only files, that meet all four conditions are searched for unit
+doctests. You can modify this behaviour of course, which will be
+explained below in detail.
+
+
+What options are set by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many options can be set, when registering unit doctests. When using
+the default set of options, the following values are set::
+
+* The setup-instance's ``setUp``-method is set as the ``setUp``
+  function.
+
+* The setup-instance's ``tearDown``-method is set as the ``tearDown``
+  function.
+  
+     >>> setup.setUp
+     <bound method UnitTestSetup.setUp of
+      <grok.testing.UnitTestSetup object at 0x...>>
+
+* The setup-instance's `optionsflags` attribute is passed. It
+  includes by default the following doctest constants:
+
+     >>> from zope.testing import doctest
+     >>> setup.optionflags == (doctest.ELLIPSIS+
+     ...                       doctest.NORMALIZE_WHITESPACE |
+     ...                       doctest.REPORT_NDIFF)
+     True
+
+* Furthermore, additional keyword parameters are passed, which were
+  set when calling the constructor. These keywords are stored in the
+  setup object as `additional_options`. Those are empty by default::
+
+     >>> setup.additional_options
+     {}
+
+No other options/parameters are set by default.
+
+
+Customizing unit test setup:
+----------------------------
+
+You can modify the behaviour of grok.testing.UnitTestSetup such, that
+a different set of files is registered and/or the found tests are
+registered with a different set of parameters/options. We will first
+discuss modifying the set of files to be searched.
+
+
+Customizing the doctest file search:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The searching of appropriate doctest files is basically done by the
+base class `BasicTestSetup`. Its purpose is to determine the set of
+files in a package, that contain unit tests. See the testfile
+`basicsetup.py` to learn more about the procedure.
+
+The unit test setup, however, requires that files contain the above
+mentioned ReStructured Text meta-marker::
+
+    `:Test-Layer: unit`
+
+This is determined by a list of regular expressions, which is also
+available as an object attribute::
+
+    >>> setup.regexp_list
+    ['^\\\\s*:(T|t)est-(L|l)ayer:\\\\s*(unit)\\\\s*']
+
+This is the default value of unit test setups.
+
+There is one file in the `cave` subpackage, which includes that
+marker. We can get the list of test files using
+`getDocTestFiles()``::
+
+    >>> testfile_list = setup.getDocTestFiles()
+    >>> testfile_list
+    ['...file1.rst']
+
+    >>> len(testfile_list)
+    1
+
+The ``isTestFile()`` method of our setup object did the filtering
+here::
+
+    >>> setup.isTestFile(testfile_list[0])
+    True
+
+The file file1.txt does not contain a unit test marker::
+
+    >>> import os.path
+    >>> path = os.path.join(os.path.dirname(cave.__file__),
+    ...                     'test1.txt')
+    >>> setup.isTestFile(path)
+    False
+
+The `regexp_list` attribute of a ``UnitTestSetup`` contains a
+list of regular expressions, of which each one must at least match one
+line of a searched file to be accepted. If you want to include files
+with different marker-strings, just change this attribute. The value
+will influence behaviour of the `isTestFile()``, ``getDocTestFiles()``
+and ``getTestSuite()`` methods.
+
+If you need more complex checks here, you can derive your customized
+test setup class and overwrite ``isTestFile()``.
+
+See `basicsetup.py` for further methods how to modify test file
+search, for example by choosing another set of accepted filename
+extensions.
+
+
+Customizing the unit test setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To customize the setup of your tests, just modify the appropriate
+attributes as explained before.
+
+To setup a different setUp or tearDown function, you can define a
+derived class, that overwrites these methods.
+
+A convenient way to pass keyword parameters to the test setup, which
+do not appear in the attributes, is passing these keywords (and the
+values) to the constructor::
+
+    >>> encoded_setup = UnitTestSetup(cave,
+    ...                               encoding='utf-8')
+
+This will read all doctests 'utf-8' encoded, which allow umlauts and
+similar chars in tests. Note, however, that you can archieve this very
+special behaviour also by writing an appropriate encoding string in
+the head of the doctest file.
+
+All keywords passed to the constructor (except 'filter_func' and
+'extensions') are also given to each individual test setup 'as-is'.
+
+Alternatively you can also modify the `additional_options` dictionary
+of a ``UnitTestSetup`` object.
+
+    >>> encoded_setup.additional_options
+    {'encoding': 'utf-8'}
+
+    >>> encoded_setup.additional_options['encoding'] = 'latin1'
+
+
+
+"""



More information about the Checkins mailing list