[Checkins] SVN: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/
Add tests for 'normal' python test setups.
Uli Fouquet
uli at gnufix.de
Sun Feb 3 03:36:36 EST 2008
Log message for revision 83443:
Add tests for 'normal' python test setups.
Changed:
U Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt
A Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/file1.py
A Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/notatest2.py
A Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/samplesetup_short3.py
A Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/unittestsetup.txt
-=-
Modified: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt 2008-02-03 07:45:54 UTC (rev 83442)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/testrunner.txt 2008-02-03 08:36:36 UTC (rev 83443)
@@ -46,16 +46,14 @@
dotted name notation. We can instead also pass the package itself, if
it was loaded before. This results in a slight longer example::
- >>> #import os
- >>> #cavepath = os.path.join(os.path.dirname(__file__), 'tests', 'cave')
>>> 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)
- <BLANKLINE>
+
Here we register all doctests from the ``cave`` module. Let's start a
testrunner with this setup::
@@ -77,7 +75,39 @@
Total: 3 tests, 0 failures, 0 errors in ... 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::
+
+ >>> import sys
+ >>> defaults = [
+ ... '--path', cavepath,
+ ... '--tests-pattern', '^samplesetup_short3$',
+ ... ]
+ >>> sys.argv = 'test -vv'.split()
+ >>> from zope.testing import testrunner
+ >>> testrunner.run(defaults)
+ Running tests at level 1
+ Running unit tests:
+ Running:
+ testFoo (z3c.testsetup.tests.cave.file1.TestTest)
+ Ran 1 tests with 0 failures and 0 errors in ... seconds.
+ False
+
+
Extended setups
---------------
Added: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/file1.py
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/file1.py (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/file1.py 2008-02-03 08:36:36 UTC (rev 83443)
@@ -0,0 +1,17 @@
+"""
+Tests with real TestCase objects.
+
+:Test-Layer: python
+
+"""
+
+import unittest
+
+class TestTest(unittest.TestCase):
+
+ def setUp(self):
+ pass
+
+ def testFoo(self):
+ self.assertEqual(2, 1+1)
+
Added: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/notatest2.py
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/notatest2.py (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/notatest2.py 2008-02-03 08:36:36 UTC (rev 83443)
@@ -0,0 +1,17 @@
+"""
+Tests with real TestCase objects.
+
+:Test-Layer: False
+
+"""
+
+import unittest
+
+class TestTest(unittest.TestCase):
+
+ def setUp(self):
+ pass
+
+ def testFoo(self):
+ self.assertEqual(2, 1+1)
+
Added: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/samplesetup_short3.py
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/samplesetup_short3.py (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/tests/cave/samplesetup_short3.py 2008-02-03 08:36:36 UTC (rev 83443)
@@ -0,0 +1,4 @@
+import z3c.testsetup
+from z3c.testsetup.tests import cave
+
+test_suite = z3c.testsetup.register_pytests(cave)
Added: Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/unittestsetup.txt
===================================================================
--- Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/unittestsetup.txt (rev 0)
+++ Sandbox/ulif/z3c-testsetup/trunk/src/z3c/testsetup/unittestsetup.txt 2008-02-03 08:36:36 UTC (rev 83443)
@@ -0,0 +1,193 @@
+##############################################################################
+#
+# Copyright (c) 2008 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 tests contained in a
+package. The most important method therefore might be
+``getTestSuite()``, which searches a given package for modules with
+unittests and returns all tests found as a suite of unit tests.
+
+This setup type does *not* look for doctests! Only 'real' python
+tests, i.e. python files with ``unittest.TestCase`` classes are found.
+
+The work is done mainly in two stages:
+
+1) The package is searched for appropriate modules, based on the
+ settings of instcance attributes.
+
+2) The tests contained in the found modules are setup as unit tests
+ and added to a ``unittest.TestSuite`` instance.
+
+There are some 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 z3c.testsetup.tests import cave
+
+Using the ``UnitTestSetup`` then is easy::
+
+ >>> from z3c.testsetup import UnitTestSetup
+ >>> setup = UnitTestSetup(cave)
+ >>> setup
+ <z3c.testsetup.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 zope 3 project now can be that
+short::
+
+ import unittest
+ import z3c.testsetup
+ import cave
+ def test_suite():
+ setup = z3c.testsetup.UnitTestSetup(cave)
+ return setup.getTestSuite()
+
+This will find all modules 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`.
+
+Note: in many test setups you will find a code fragment like the
+ following at the end of file::
+
+ if __name__ == '__main__':
+ unittest.main(default='test_suite')
+
+ This is not neccessary for usual testrunner setups. A testrunner
+ will look for appropriate filenames (modules) and if those
+ modules provide a callable ``test_suite`` (usually a function)
+ this callable will be called to deliver a test suite.
+
+
+UnitTestSetup default values
+----------------------------
+
+Understanding the defaults is important, because the default values
+are driving the whole process of finding and registering the test.
+
+
+Which modules are found by default?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basically, all modules are accepted that
+
+1) reside inside the package passed to the constructor. This includes
+ subpackages.
+
+2) contain a ReStructured Text meta-marker in their module docstring,
+ that defines the module as a testing module
+ explicitly::
+
+ :Test-Layer: python
+
+ This means: there *must* be a line like the above one in the
+ docstring of the module (not: docstring of a class or function
+ therein). The term might be preceeded or followed by whitspace
+ characters (spaces, tabs).
+
+ For example a module `example.py` would be found if it contains::
+
+ """
+ Tests to foo.
+
+ :Test-Layer: python
+ """
+ import unittest
+
+ class TestSomething(unittest.TestCase):
+ def testOne(self):
+ self.assertEqual(2, 1+1)
+
+ because the docstring of the *module* contains the required string.
+
+
+Only files, that meet both conditions are found and registered. You
+can modify this behaviour of course, which will be explained below in
+detail.
+
+Customizing unit test setup:
+----------------------------
+
+You can modify the behaviour of z3c.testsetup.UnitTestSetup such, that
+a different set of modules is registered.
+
+
+Customizing the test module search:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The unit test setup requires that files contain the above mentioned
+ReStructured Text meta-marker::
+
+ `:Test-Layer: unit`
+
+in their module docstring. 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*(python)\\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
+`getTestFiles()``::
+
+ >>> testfile_list = setup.getModules()
+ >>> testfile_list
+ [<module 'z3c.testsetup.tests.cave.file1' from ...>]
+
+ >>> len(testfile_list)
+ 1
+
+The ``isTestModule()`` method of our setup object did the filtering
+here::
+
+ >>> setup.isTestModule(testfile_list[0])
+ True
+
+The `notatest2` module in `cave` does not contain a unit test marker::
+
+ >>> from z3c.testsetup.tests.cave import notatest2
+ >>> setup.isTestModule(notatest2)
+ 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 `isTestModule()``, ``getDocTestFiles()``
+and ``getTestSuite()`` methods.
+
+If you need more complex checks here, you can derive your customized
+test setup class and overwrite ``isTestModule()``.
+
+
+
+"""
More information about the Checkins
mailing list