API Reference

zope.testing.cleanup

Provide a standard cleanup registry

Unit tests that change global data should include the CleanUp base class, which provides simpler setUp and tearDown methods that call global-data cleanup routines:

class Test(CleanUp, unittest.TestCase):

    ....

If custom setUp or tearDown are needed, then the base routines should be called, as in:

def tearDown(self):
    super(Test, self).tearDown()
    ....

Cleanup routines for global data should be registered by passing them to addCleanup:

addCleanUp(pigRegistry._clear)
zope.testing.cleanup.addCleanUp(func, args=(), kw={})[source]

Register a cleanup routines

Pass a function to be called to cleanup global data. Optional argument tuple and keyword arguments may be passed.

class zope.testing.cleanup.CleanUp[source]

Bases: object

Mix-in class providing clean-up setUp and tearDown routines.

cleanUp()[source]

Clean up global data.

setUp()

Clean up global data.

tearDown()

Clean up global data.

zope.testing.cleanup.cleanUp()[source]

Clean up global data.

zope.testing.cleanup.setUp()

Clean up global data.

zope.testing.cleanup.tearDown()

Clean up global data.

zope.testing.doctestcase

Doctests in TestCase classes

The original doctest unittest integration was based on unittest test suites, which have fallen out of favor. This module provides a way to define doctests inside of unittest TestCase classes. It also provides better integration with unittest test fixtures, because doctests use setup provided by the containing test case class. It also provides access to unittest assertion methods.

You can define doctests in 4 ways:

  • references to named files

  • strings

  • decorated functions with docstrings

  • reference to named files decorating test-specific setup functions

Here are some examples:

from zope.testing import doctestcase
import doctest
import unittest

g = 'global'
class MyTest(unittest.TestCase):

    def setUp(self):
        self.a = 1
        self.globs = dict(c=9)

    test1 = doctestcase.file('test1.txt', optionflags=doctest.ELLIPSIS)

    test2 = doctestcase.docteststring('''
      >>> self.a, g, c
      (1, 'global', 9)
    ''')

    @doctestcase.doctestmethod(optionflags=doctest.ELLIPSIS)
    def test3(self):
        '''
        >>> self.a, self.x, g, c
        (1, 3, 'global', 9)
        '''
        self.x = 3

    @doctestcase.doctestfile('test4.txt')
    def test4(self):
        self.x = 5

In this example, 3 constructors were used:

doctestfile (alias: file)

doctestfile makes a file-based test case.

This can be used as a decorator, in which case, the decorated function is called before the test is run, to provide test-specific setup.

docteststring (alias string)

docteststring constructs a doctest from a string.

doctestmethod (alias method)

doctestmethod constructs a doctest from a method.

The method’s docstring provides the test. The method’s body provides optional test-specific setup.

Note that short aliases are provided, which may be useful in certain import styles.

Tests have access to the following data:

  • Tests created with the docteststring and doctestmethod constructors have access to the module globals of the defining module.

  • In tests created with the docteststring and doctestmethod constructors, the test case instance is available as the self variable.

  • In tests created with the doctestfile constructor, the test case instance is available as the test variable.

  • If a test case defines a globs attribute, it must be a dictionary and its contents are added to the test globals.

The constructors accept standard doctest optionflags and checker arguments.

Note that the doctest IGNORE_EXCEPTION_DETAIL option flag is added to optionflags.

zope.testing.doctestcase.doctestmethod(test=None, optionflags=0, checker=None)[source]

Define a doctest from a method within a unittest.TestCase.

The method’s doc string provides the test source. Its body is called before the test and may perform test-specific setup.

You can pass doctest option flags and a custon checker.

Variables defined in the enclosing module are available in the test.

If a test case defines a globs attribute, it must be a dictionary and its contents are added to the test globals.

The test object is available as the variable self in the test.

zope.testing.doctestcase.docteststring(test, optionflags=0, checker=None, name=None)[source]

Define a doctest from a string within a unittest.TestCase.

You can pass doctest option flags and a custon checker.

Variables defined in the enclosing module are available in the test.

If a test case defines a globs attribute, it must be a dictionary and its contents are added to the test globals.

The test object is available as the variable self in the test.

zope.testing.doctestcase.doctestfile(path, optionflags=0, checker=None)[source]

Define a doctest from a test file within a unittest.TestCase.

The file path may be relative or absolute. If its relative (the common case), it will be interpreted relative to the directory containing the referencing module.

You can pass doctest option flags and a custon checker.

If a test case defines a globs attribute, it must be a dictionary and its contents are added to the test globals.

The test object is available as the variable test in the test.

The resulting object can be used as a function decorator. The decorated method is called before the test and may perform test-specific setup. (The decorated method’s doc string is ignored.)

zope.testing.exceptions

Exceptions for zope.testing

exception zope.testing.exceptions.DocTestFailureException[source]

Bases: AssertionError

Use custom exception for doctest unit test failures

zope.testing.formparser

zope.testing.loggingsupport

class zope.testing.loggingsupport.Handler(*names, **kw)[source]

Bases: logging.Handler

Initializes the instance - basically setting the formatter to None and the filter list to empty.

emit(record)[source]

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

class zope.testing.loggingsupport.InstalledHandler(*names, **kw)[source]

Bases: zope.testing.loggingsupport.Handler

Initializes the instance - basically setting the formatter to None and the filter list to empty.

zope.testing.loghandler

logging handler for tests that check logging output.

class zope.testing.loghandler.Handler(testcase, propagate=False)[source]

Bases: logging.Handler

Handler for use with unittest.TestCase objects.

The handler takes a TestCase instance as a constructor argument. It can be registered with one or more loggers and collects log records they generate.

The assertLogsMessage() and failIfLogsMessage() methods can be used to check the logger output and causes the test to fail as appropriate.

Initializes the instance - basically setting the formatter to None and the filter list to empty.

close()[source]

Remove handler from any loggers it was added to.

add(name)[source]

Add handler to logger named name.

emit(record)[source]

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

zope.testing.module

Fake module support

zope.testing.renormalizing

class zope.testing.renormalizing.OutputChecker(patterns=None)[source]

Bases: doctest.OutputChecker

Pattern-normalizing output checker

check_output(want, got, optionflags)[source]

Return True iff the actual output from an example (got) matches the expected output (want). These strings are always considered to match if they are identical; but depending on what option flags the test runner is using, several non-exact match types are also possible. See the documentation for TestRunner for more information about option flags.

output_difference(example, got, optionflags)[source]

Return a string describing the differences between the expected output for a given example (example) and the actual output (got). optionflags is the set of option flags used to compare want and got.

zope.testing.renormalizing.RENormalizing

alias of zope.testing.renormalizing.OutputChecker

zope.testing.server

zope.testing.setupstack

Stack-based test doctest setUp and tearDown

See setupstack.txt

class zope.testing.setupstack.TestCase(methodName='runTest')[source]

Bases: unittest.case.TestCase

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

tearDown()

Hook method for deconstructing the test fixture after testing it.

zope.testing.wait