plone.testing 7.0.3

unittest

Please note that the zope.testing test runner at the time of writing (version 4.6.2) does not (yet) support the new setUpClass(), tearDownClass(), setUpModule() and tearDownModule() hooks from unittest. This is not normally a problem, since we tend to use layers to manage complex fixtures, but it is important to be aware of nonetheless.

Test modules, classes and functions

Python tests are written with classes that derive from the base class TestCase. Each test is written as a method that takes no arguments and has a name starting with test. Other methods can be added and called from test methods as appropriate, e.g. to share some test logic.

Two special methods, setUp() and tearDown(), can also be added. These will be called before or after each test, respectively, and provide a useful place to construct and clean up test fixtures without writing a custom layer. They are obviously not as re-usable as layers, though.

Hint: Somewhat confusingly, the setUp() and tearDown() methods in a test case class are the equivalent of the testSetUp() and testTearDown() methods of a layer class.

A layer can be specified by setting the layer class attribute to a layer instance. If layers are used in conjunction with setUp() and tearDown() methods in the test class itself, the class’ setUp() method will be called after the layer’s testSetUp() method, and the class’ tearDown() method will be called before the layer’s testTearDown() method.

The TestCase base class contains a number of methods which can be used to write assertions. They all take the form self.assertSomething(), e.g. self.assertEqual(result, expectedValue). See the unittest documentation for details.

Putting this together, let’s expand on our previous example unit test::

>>> import unittest

>>> class TestFasterThanLightTravel(unittest.TestCase):
...     layer = GALAXY_CLASS_SPACE_SHIP
...
...     def setUp(self):
...         self.warpDrive = self.layer['warpDrive']
...         self.warpDrive.stop()
...
...     def tearDown(self):
...         self.warpDrive.stop()
...
...     def test_warp8(self):
...         self.warpDrive.start(8)
...         self.assertEqual(self.warpDrive.running, True)
...
...     def test_max_speed(self):
...         tooFast = self.warpDrive.maxSpeed + 0.1
...         self.warpDrive.start(tooFast)
...         self.assertEqual(self.warpDrive.running, False)

A few things to note:

• The class derives from unittest.TestCase.

• The layer class attribute is set to a layer instance (not a layer class!) defined previously. This would typically be imported from a testing module.

• There are two tests here: test_warp8() and test_max_speed().

• We have used the self.assertEqual() assertion in both tests to check the result of executing the start() method on the warp drive.

• We have used the setUp() method to fetch the warpDrive resource and ensure that it is stopped before each test is executed. Assigning a variable to self is a useful way to provide some state to each test method, though be careful about data leaking between tests: in general, you cannot predict the order in which tests will run, and tests should always be independent.

• We have used the tearDown() method to make sure the warp drive is really stopped after each test.

Test suites

A class like the one above is all you need: any class deriving from TestCase in a module with a name starting with test will be examined for test methods. Those tests are then collected into a test suite and executed.

See the unittest documentation for other options.

Docstring doctests

Doctests can be added to any module, class or function docstring::

def canOutrunKlingons(warpDrive):
    """Find out of the given warp drive can outrun Klingons.

    Klingons travel at warp 8

    >>> drive = WarpDrive(5)
    >>> canOutrunKlingons(drive)
    False

    We have to be faster than that to outrun them.

    >>> drive = WarpDrive(8.1)
    >>> canOutrunKlingons(drive)
    True

    We can't outrun them if we're travelling exactly the same speed

    >>> drive = WarpDrive(8.0)
    >>> canOutrunKlingons(drive)
    False

    """
    return warpDrive.maxSpeed > 8.0

To add the doctests from a particular module to a test suite, you need to use the test_suite() function hook::

>>> import doctest
>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         unittest.makeSuite(TestFasterThanLightTravel), # our previous test
...         doctest.DocTestSuite('spaceship.utils'),
...     ])
...     return suite

Here, we have given the name of the module to check as a string dotted name. It is also possible to import a module and pass it as an object. The code above passes a list to addTests(), making it easy to add several sets of tests to the suite: the list can be constructed from calls to DocTestSuite(), DocFileSuite() (shown below) and makeSuite() (shown above).

Remember that if you add a test_suite() function to a module that also has TestCase-derived python tests, those tests will no longer be automatically picked up by zope.testing, so you need to add them to the test suite explicitly.

The example above illustrates a documentation-oriented doctest, where the doctest forms part of the docstring of a public module. The same syntax can be used for more systematic unit tests. For example, we could have a module spaceship.tests.test_spaceship with a set of methods like:

# It's often better to put the import into each method, but here we've
# imported the code under test at module level
from spaceship.utils import WarpDrive, canOutrunKlingons

def test_canOutrunKlingons_too_small():
    """Klingons travel at warp 8.0

    >>> drive = WarpDrive(7.9)
    >>> canOutrunKlingons(drive)
    False

    """

def test_canOutrunKlingons_big():
    """Klingons travel at warp 8.0

    >>> drive = WarpDrive(8.1)
    >>> canOutrunKlingons(drive)
    True

    """

def test_canOutrunKlingons_must_be_greater():
    """Klingons travel at warp 8.0

    >>> drive = WarpDrive(8.0)
    >>> canOutrunKlingons(drive)
    False

    """

Here, we have created a number of small methods that have no body. They merely serve as a container for docstrings with doctests. Since the module has no globals, each test must import the code under test, which helps make import errors more explicit.

File doctests

Doctests contained in a file are similar to those contained in docstrings. File doctests are better suited to narrative documentation covering the usage of an entire module or package.

For example, if we had a file called spaceship.txt with doctests, we could add it to the test suite above with::

>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         unittest.makeSuite(TestFasterThanLightTravel),
...         doctest.DocTestSuite('spaceship.utils'),
...         doctest.DocFileSuite('spaceship.txt'),
...     ])
...     return suite

By default, the file is located relative to the module where the test suite is defined. You can use ../ (even on Windows) to reference the parent directory, which is sometimes useful if the doctest is inside a module in a tests package.

It is possible to pass several tests to the suite, e.g.:

>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         unittest.makeSuite(TestFasterThanLightTravel),
...         doctest.DocTestSuite('spaceship.utils'),
...         doctest.DocFileSuite('spaceship.txt', 'warpdrive.txt',),
...     ])
...     return suite

The test runner will report each file as a separate test, i.e. the DocFileSuite() above would add two tests to the overall suite. Conversely, a DocTestSuite() using a module with more than one docstring containing doctests will report one test for each eligible docstring.

Doctest fixtures and layers

A docstring doctest will by default have access to any global symbol available in the module where the docstring is found (e.g. anything defined or imported in the module). The global namespace can be overridden by passing a globs keyword argument to the DocTestSuite() constructor, or augmented by passing an extraglobs argument. Both should be given dictionaries.

A file doctest has an empty globals namespace by default. Globals may be provided via the globs argument to DocFileSuite().

To manage a simple test fixture for a doctest, you can define set-up and tear-down functions and pass them as the setUp and tearDown arguments respectively. These are both passed a single argument, a DocTest object. The most useful attribute of this object is globs, which is a mutable dictionary of globals available in the test.

For example::

>>> def setUpKlingons(doctest):
...     doctest.globs['oldStyleKlingons'] = True

>>> def tearDownKlingons(doctest):
...     doctest.globs['oldStyleKlingons'] = False

>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         doctest.DocTestSuite('spaceship.utils', setUp=setUpKlingons, tearDown=tearDownKlingons),
...     ])
...     return suite

The same arguments are available on the DocFileSuite() constructor. The set up method is called before each docstring in the given module for a DocTestSuite, and before each file given in a DocFileSuite.

Of course, we often want to use layers with doctests too. Unfortunately, the unittest API is not aware of layers, so you can’t just pass a layer to the DocTestSuite() and DocFileSuite() constructors. Instead, you have to set a layer attribute on the suite after it has been constructed.

Furthermore, to use layer resources in a doctest, we need access to the layer instance. The easiest way to do this is to pass it as a glob, conventionally called ‘layer’. This makes a global name ‘layer’ available in the doctest itself, giving access to the test’s layer instance.

To make it easier to do this, plone.testing comes with a helper function called layered(). Its first argument is a test suite. The second argument is the layer.

For example::

>>> from plone.testing import layered
>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         layered(doctest.DocTestSuite('spaceship.utils'), layer=CONSTITUTION_CLASS_SPACE_SHIP),
...     ])
...     return suite

This is equivalent to::

>>> def test_suite():
...     suite = unittest.TestSuite()
...
...     spaceshipUtilTests = doctest.DocTestSuite('spaceship.utils', globs={'layer': CONSTITUTION_CLASS_SPACE_SHIP})
...     spaceshipUtilTests.layer = CONSTITUTION_CLASS_SPACE_SHIP
...     suite.addTest(spaceshipUtilTests)
...
...     return suite

(In this example, we’ve opted to use addTest() to add a single suite, instead of using addTests() to add multiple suites in one go).

Unit testing

This layer does not set up a fixture per se, but cleans up global state before and after each test, using zope.testing.cleanup as described above.

The net result is that each test has a clean global component registry. Thus, it is safe to use the zope.component Python API (provideAdapter(), provideUtility(), provideHandler() and so on) to register components.

Be careful with using this layer in combination with other layers. Because it tears down the component registry between each test, it will clobber any layer that sets up more permanent test fixture in the component registry.

Event testing

This layer extends the zca.UNIT_TESTING layer to enable the eventtesting support from zope.component. Using this layer, you can import and use zope.component.eventtesting.getEvent to inspect events fired by the code under test.

See above for details.

Layer cleanup

This layer calls the cleanup functions from zope.testing.cleanup on setup and tear-down (but not between each test). It is useful as a base layer for other layers that need an environment as pristine as possible.

Basic ZCML directives

This registers a minimal set of ZCML directives, principally those found in the zope.component package, and makes available a configuration context. This allows custom ZCML to be loaded as described above.

The configurationContext resource should be used when loading custom ZCML. To ensure isolation, you should stack this using the stackConfigurationContext() helper. For example, if you were writing a setUp() method in a layer that had zca.ZCML_DIRECTIVES as a base, you could do::

self['configurationContext'] = context = zca.stackConfigurationContext(self.get('configurationContext'))
xmlconfig.string(someZCMLString, context=context)

This will create a new configuration context with the state of the base layer’s context. On tear-down, you should delete the layer-specific resource::

del self['configurationContext']

See above for more details about loading custom ZCML in a layer or test.

ZCML files helper class

The ZCMLSandbox can be instantiated with a filename and package arguments:

ZCML_SANDBOX = zca.ZCMLSandbox(filename="configure.zcml",
    package=my.package)

That layer setUp loads the ZCML file. It avoids the need to using (and understand) configurationContext and globalRegistry until you need more flexibility or modularity for your layer and tests.

See above for more details about loading custom ZCML in a layer or test.

Helper functions

The following helper functions are available in the plone.testing.zca module.

stackConfigurationContext(context=None)

Create and return a copy of the passed-in ZCML configuration context, or a brand new context if it is None.

The purpose of this is to ensure that if a layer loads some ZCML files (using the zope.configuration API during) during its setUp(), the state of the configuration registry (which includes registered directives as well as a list of already imported files, which will not be loaded again even if explicitly included) can be torn down during tearDown().

The usual pattern is to keep the configuration context in a layer resource called configurationContext. In setUp(), you would then use:

self['configurationContext'] = context = zca.stackConfigurationContext(self.get('configurationContext'))

# use 'context' to load some ZCML

In tearDown(), you can then simply do:

del self['configurationContext']

pushGlobalRegistry(new=None)

Create or obtain a stack of global component registries, and push a new registry to the top of the stack. The net result is that zope.component.getGlobalSiteManager() and (an un-hooked) getSiteManager() will return the new registry instead of the default, module-scope one. From this point onwards, calls to provideAdapter(), provideUtility() and other functions that modify the global registry will use the new registry.

If new is not given, a new registry is created that has the previous global registry (site manager) as its sole base. This has the effect that registrations in the previous default global registry are still available, but new registrations are confined to the new registry.

Warning: If you call this function, you must reciprocally call popGlobalRegistry(). That is, if you “push” a registry during layer setUp(), you must “pop” it during tearDown(). If you “push” during testSetUp(), you must “pop” during testTearDown(). If the calls to push and pop are not balanced, you will leave your global registry in a mess, which is not pretty.

Returns the new default global site manager. Also causes the site manager hook from zope.component.hooks to be reset, clearing any local site managers as appropriate.

popGlobalRegistry()

Pop the global site registry, restoring the previous registry to be the default.

Please heed the warning above: push and pop must be balanced.

Returns the new default global site manager. Also causes the site manager hook from zope.component.hooks to be reset, clearing any local site managers as appropriate.

Security checker isolation

This layer ensures that security checkers used by zope.security are isolated. Any checkers set up in a child layer will be removed cleanly during tear-down.

Helper functions

The security checker isolation outlined above is managed using two helper functions found in the module plone.testing.security:

pushCheckers()

Copy the current set of security checkers for later tear-down.

popCheckers()

Restore the set of security checkers to the state of the most recent call to pushCheckers().

You must keep calls to pushCheckers() and popCheckers() in balance. That usually means that if you call the former during layer setup, you should call the latter during layer tear-down. Ditto for calls during test setup/tear-down or within tests themselves.

Publisher directives

This layer extends the zca.ZCML_DIRECTIVES layer to install additional ZCML directives in the browser namespace (from zope.app.publisher.browser) as well as those from zope.security. This allows browser views, browser pages and other UI components to be registered, as well as the definition of new permissions.

As with zca.ZCML_DIRECTIVES, you should use the configurationContext resource when loading ZCML strings or files, and the stackConfigurationRegistry() helper to create a layer-specific version of this resource resource. See above.

Empty ZODB sandbox

This layer sets up a simple ZODB sandbox using DemoStorage. The ZODB root object is a simple persistent mapping, available as the resource zodbRoot. The ZODB database object is available as the resource zodbDB. The connection used in the test is available as zodbConnection.

Note that the zodbConnection and zodbRoot resources are created and destroyed for each test. You can use zodbDB (and the open() method) if you are writing a layer based on this one and need to set up a fixture during layer set up. Don’t forget to close the connection before concluding the test setup!

A new transaction is begun for each test, and rolled back (aborted) on test tear-down. This means that so long as you don’t use transaction.commit() explicitly in your code, it should be safe to add or modify items in the ZODB root.

If you want to create a test fixture with persistent data in your own layer based on EMPTY_ZODB, you can use the following pattern:

from plone.layer import Layer
from plone.layer import zodb

class MyLayer(Layer):
    defaultBases = (zodb.EMPTY_ZODB,)

    def setUp(self):

        import transaction
        self['zodbDB'] = db = zodb.stackDemoStorage(self.get('zodbDB'), name='MyLayer')

        conn = db.open()
        root = conn.root()

        # modify the root object here

        transaction.commit()
        conn.close()

    def tearDown(self):

        self['zodbDB'].close()
        del self['zodbDB']

This shadows the zodbDB resource with a new database that uses a new DemoStorage stacked on top of the underlying database storage. The fixture is added to this storage and committed during layer setup. (The base layer test set-up/tear-down will still begin and abort a new transaction for each test). On layer tear-down, the database is closed and the resource popped, leaving the original zodbDB database with the original, pristine storage.

Helper functions

One helper function is available in the plone.testing.zodb module.

stackDemoStorage(db=None, name=None)

Create a new DemoStorage using the storage from the passed-in database as a base. If db is None, a brand new storage is created.

A name can be given to uniquely identify the storage. It is optional, but it is often useful for debugging purposes to pass the name of the layer.

The usual pattern is:

def setUp(self):
    self['zodbDB'] = zodb.stackDemoStorage(self.get('zodbDB'), name='MyLayer')

def tearDown(self):
    self['zodbDB'].close()
    del self['zodbDB']

This will shadow the zodbDB resource with an isolated DemoStorage, creating a new one if that resource does not already exist. All existing data continues to be available, but new changes are written to the stacked storage. On tear-down, the stacked database is closed and the resource removed, leaving the original data.

Startup

This layer sets up a Zope environment, and is a required base for all other Zope layers. You cannot run two instances of this layer in parallel, since Zope depends on some module-global state to run, which is managed by this layer.

On set-up, the layer will configure a Zope environment with:

• Debug mode enabled.

• ZEO client cache disabled.

• Some patches installed, which speed up Zope startup by disabling some superfluous aspects of Zope.

• One thread (this only really affects the WSGI_SERVER, ZSERVER and FTP_SERVER layers).

• A pristine database using DemoStorage, exposed as the resource zodbDB. Zope is configured to use this database in a way that will also work if the zodbDB resource is shadowed using the pattern shown above in the description of the zodb.EMPTY_ZODB layer.

• A fake hostname and port, exposed as the host and port resource, respectively.

• A minimal set of products installed (Products.OFSP and Products.PluginIndexes, both required for Zope to start up).

• A stacked ZCML configuration context, exposed as the resource configurationContext. As illustrated above, you should use the zca.stackConfigurationContext() helper to stack your own configuration context if you use this.

• A minimal set of global Zope components configured.

Note that unlike a “real” Zope site, products in the Products.* namespace are not automatically loaded, nor is any ZCML.

Integration test

This layer is intended for integration testing against the simple STARTUP fixture. If you want to create your own layer with a more advanced, shared fixture, see “Integration and functional testing with custom fixtures” below.

For each test, it exposes the Zope application root as the resource app. This is wrapped in the request container, so you can do app.REQUEST to acquire a fake request, but the request is also available as the resource request.

A new transaction is begun for each test and rolled back on test tear-down, meaning that so long as the code under test does not explicitly commit any changes, the test may modify the ZODB.

Hint: If you want to set up a persistent test fixture in a layer based on this one (or zope.FUNCTIONAL_TESTING), you can stack a new DemoStorage in a shadowing zodbDB resource, using the pattern described above for the zodb.EMPTY_ZODB layer.

Once you’ve shadowed the zodbDB resource, you can do (e.g. in your layer’s setUp() method):

...
with zope.zopeApp() as app:
    # modify the Zope application root

The zopeApp() context manager will open a new connection to the Zope application root, accessible here as app. Provided the code within the with block does not raise an exception, the transaction will be committed and the database closed properly upon exiting the block.

Functional testing

This layer is intended for functional testing against the simple STARTUP fixture. If you want to create your own layer with a more advanced, shared fixture, see “Integration and functional testing with custom fixtures” below.

As its name implies, this layer is intended mainly for functional end-to-end testing using tools like zope.testbrowser. See also the Browser object as described under “Helper functions” below.

This layer is very similar to INTEGRATION_TESTING, but is not based on it. It sets up the same fixture and exposes the same resources. However, instead of using a simple transaction abort to isolate the ZODB between tests, it uses a stacked DemoStorage for each test. This is slower, but allows test code to perform and explicit commit, as will usually happen in a functional test.

Integration and functional testing with custom fixtures

If you want to extend the STARTUP fixture for use with integration or functional testing, you should use the following pattern:

• Create a layer class and a “fixture” base layer instance that has zope.STARTUP (or some intermediary layer, such as zope.WSGI_SERVER_FIXTURE, shown below) as a base.

• Create “end user” layers by instantiating the zope.IntegrationTesting and/or FunctionalTesting classes with this new “fixture” layer as a base.

This allows the same fixture to be used regardless of the “style” of testing, minimising the amount of set-up and tear-down. The “fixture” layers manage the fixture as part of the layer lifecycle. The layer class (IntegrationTesting or FunctionalTesting), manages the test lifecycle, and the test lifecycle only.

For example:

from plone.testing import Layer, zope, zodb

class MyLayer(Layer):
    defaultBases = (zope.STARTUP,)

    def setUp(self):
        # Set up the fixture here
        ...

    def tearDown(self):
        # Tear down the fixture here
        ...

MY_FIXTURE = MyLayer()

MY_INTEGRATION_TESTING = zope.IntegrationTesting(bases=(MY_FIXTURE,), name="MyFixture:Integration")
MY_FUNCTIONAL_TESTING = zope.FunctionalTesting(bases=(MY_FIXTURE,), name="MyFixture:Functional")

(Note that we need to give an explicit, unique name to the two layers that re-use the IntegrationTesting and FunctionalTesting classes.)

In this example, other layers could extend the “MyLayer” fixture by using MY_FIXTURE as a base. Tests would use either MY_INTEGRATION_TESTING or MY_FUNCTIONAL_TESTING as appropriate. However, even if both these two layers were used, the fixture in MY_FIXTURE would only be set up once.

It may be preferable, therefore, to have your own “test lifecycle” layer classes that subclass IntegrationTesting and/or FunctionalTesting and call base class methods as appropriate. plone.app.testing takes this approach, for example.

HTTP WSGI server thread (fixture only)

This layer extends the zope.STARTUP layer to start the Zope HTTP WSGI server in a separate thread. This means the test site can be accessed through a web browser, and can thus be used with tools like Selenium.

The WSGI server’s hostname (normally localhost) is available through the resource host, whilst the port it is running on is available through the resource port.

Hint: Whilst the layer is set up, you can actually access the test Zope site through a web browser. The default URL will be http://localhost:55001.

HTTP WSGI server functional testing

This layer provides the functional testing lifecycle against the fixture set up by the zope.WSGI_SERVER_FIXTURE layer.

You can use this to run “live” functional tests against a basic Zope site. You should not use it as a base. Instead, create your own “fixture” layer that extends zope.WSGI_SERVER_FIXTURE, and then instantiate the FunctionalTesting class with this extended fixture layer as a base, as outlined above.

Helper functions

Several helper functions are available in the plone.testing.zope module.

zopeApp(db=None, conn=Non, environ=None)

This function can be used as a context manager for any code that requires access to the Zope application root. By using it in a with block, the database will be opened, and the application root will be obtained and request-wrapped. When exiting the with block, the transaction will be committed and the database properly closed, unless an exception was raised:

with zope.zopeApp() as app:
    # do something with app

If you want to use a specific database or database connection, pass either the db or conn arguments. If the context manager opened a new connection, it will close it, but it will not close a connection passed with conn.

To set keys in the (fake) request environment, pass a dictionary of environment values as environ.

Note that zopeApp() should not normally be used in tests or test set-up/tear-down, because the INTEGRATOIN_TEST and FUNCTIONAL_TESTING layers both manage the application root (as the app resource) and close it for you. It is very useful in layer setup, however.

installProduct(app, product, quiet=False)

Install a Zope 2 style product, ensuring that its initialize() function is called. The product name must be the full dotted name, e.g. plone.app.portlets or Products.CMFCore. If quiet is true, duplicate registrations will be ignored silently, otherwise a message is logged.

To get hold of the application root, passed as the app argument, you would normally use the zopeApp() context manager outlined above.

uninstallProduct(app, product, quiet=False)

This is the reciprocal of installProduct(), normally used during layer tear-down. Again, you should use zopeApp() to obtain the application root.

login(userFolder, userName)

Create a new security manager that simulates being logged in as the given user. userFolder is an acl_users object, e.g. app['acl_users'] for the root user folder.

logout()

Simulate being the anonymous user by unsetting the security manager.

setRoles(userFolder, userName, roles)

Set the roles of the given user in the given user folder to the given list of roles.

makeTestRequest()

Create a fake Zope request.

addRequestContainer(app, environ=None)

Create a fake request and wrap the given object (normally an application root) in a RequestContainer with this request. This makes acquisition of app.REQUEST possible. To initialise the request environment with non-default values, pass a dictionary as environ.

Browser(app)

Obtain a test browser client, for use with zope.testbrowser. You should use this in conjunction with the zope.FUNCTIONAL_TESTING layer or a derivative. You must pass the app root, usually obtained from the app resource of the layer, e.g.:

app = self.layer['app']
browser = zope.Browser(app)

You can then use browser as described in the zope.testbrowser documentation.

Bear in mind that the test browser runs separately from the test fixture. In particular, calls to helpers such as login() or logout() do not affect the state that the test browser sees. If you want to set up a persistent fixture (e.g. test content), you can do so before creating the test browser, but you will need to explicitly commit your changes, with:

import transaction
transaction.commit()

Startup

This layer sets up a Zope environment for ZServer, and is a required base for all other ZServer layers. You cannot run two instances of this layer in parallel, since Zope depends on some module-global state to run, which is managed by this layer.

On set-up, the layer will configure a Zope environment with the same options as zope.Startup, see there.

Integration test

This layer is intended for integration testing against the simple STARTUP fixture. If you want to create your own layer with a more advanced, shared fixture, see “Integration and functional testing with custom fixtures” below.

For each test, it exposes the Zope application root as the resource app. This is wrapped in the request container, so you can do app.REQUEST to acquire a fake request, but the request is also available as the resource request.

A new transaction is begun for each test and rolled back on test tear-down, meaning that so long as the code under test does not explicitly commit any changes, the test may modify the ZODB.

Hint: If you want to set up a persistent test fixture in a layer based on this one (or zserver.FUNCTIONAL_TESTING), you can stack a new DemoStorage in a shadowing zodbDB resource, using the pattern described above for the zodb.EMPTY_ZODB layer.

Once you’ve shadowed the zodbDB resource, you can do (e.g. in your layer’s setUp() method):

...
with zserver.zopeApp() as app:
    # modify the Zope application root

The zserver.zopeApp() context manager will open a new connection to the Zope application root, accessible here as app. Provided the code within the with block does not raise an exception, the transaction will be committed and the database closed properly upon exiting the block.

Functional testing

It behaves the same as zope.FunctionalTesting, see there.

Integration and functional testing with custom fixtures

If you want to extend the STARTUP fixture for use with integration or functional testing, you should use the following pattern:

• Create a layer class and a “fixture” base layer instance that has zserver.STARTUP (or some intermediary layer, such as zserver.ZSERVER_FIXTURE or zserver.FTP_SERVER_FIXTURE, shown below) as a base.

• Create “end user” layers by instantiating the zserver.IntegrationTesting and/or FunctionalTesting classes with this new “fixture” layer as a base.

This allows the same fixture to be used regardless of the “style” of testing, minimising the amount of set-up and tear-down. The “fixture” layers manage the fixture as part of the layer lifecycle. The layer class (IntegrationTesting or FunctionalTesting), manages the test lifecycle, and the test lifecycle only.

For example:

from plone.testing import Layer, zserver, zodb

class MyLayer(Layer):
    defaultBases = (zserver.STARTUP,)

    def setUp(self):
        # Set up the fixture here
        ...

    def tearDown(self):
        # Tear down the fixture here
        ...

MY_FIXTURE = MyLayer()

MY_INTEGRATION_TESTING = zserver.IntegrationTesting(bases=(MY_FIXTURE,), name="MyFixture:Integration")
MY_FUNCTIONAL_TESTING = zserver.FunctionalTesting(bases=(MY_FIXTURE,), name="MyFixture:Functional")

(Note that we need to give an explicit, unique name to the two layers that re-use the IntegrationTesting and FunctionalTesting classes.)

In this example, other layers could extend the “MyLayer” fixture by using MY_FIXTURE as a base. Tests would use either MY_INTEGRATION_TESTING or MY_FUNCTIONAL_TESTING as appropriate. However, even if both these two layers were used, the fixture in MY_FIXTURE would only be set up once.

It may be preferable, therefore, to have your own “test lifecycle” layer classes that subclass IntegrationTesting and/or FunctionalTesting and call base class methods as appropriate. plone.app.testing takes this approach, for example.

HTTP ZServer thread (fixture only)

This layer extends the zserver.STARTUP layer to start the Zope HTTP server (ZServer) in a separate thread. This means the test site can be accessed through a web browser, and can thus be used with tools like Selenium.

The ZServer’s hostname (normally localhost) is available through the resource host, whilst the port it is running on is available through the resource port.

Hint: Whilst the layer is set up, you can actually access the test Zope site through a web browser. The default URL will be http://localhost:55001.

HTTP ZServer functional testing

This layer provides the functional testing lifecycle against the fixture set up by the zserver.ZSERVER_FIXTURE layer.

You can use this to run “live” functional tests against a basic Zope site. You should not use it as a base. Instead, create your own “fixture” layer that extends zserver.ZSERVER_FIXTURE, and then instantiate the FunctionalTesting class with this extended fixture layer as a base, as outlined above.

FTP server thread (fixture only)

This layer is the FTP server equivalent of the zserver.ZSERVER_FIXTURE layer. It can be used to functionally test Zope FTP servers.

If you need both ZServer and FTPServer running together, you can subclass the ZServer layer class (like the FTPServer layer class does) and implement the setUpServer() and tearDownServer() methods to set up and close down two servers on different ports. They will then share a main loop.

FTP server functional testing

This layer provides the functional testing lifecycle against the fixture set up by the zserver.FTP_SERVER_FIXTURE layer.

You can use this to run “live” functional tests against a basic Zope site. You should not use it as a base. Instead, create your own “fixture” layer that extends zserver.FTP_SERVER_FIXTURE, and then instantiate the FunctionalTesting class with this extended fixture layer as a base, as outlined above.

Helper functions

Several helper functions are available in the plone.testing.zserver module.

zopeApp(db=None, conn=Non, environ=None)

This function can be used as a context manager for any code that requires access to the Zope application root. By using it in a with block, the database will be opened, and the application root will be obtained and request-wrapped. When exiting the with block, the transaction will be committed and the database properly closed, unless an exception was raised:

with zserver.zopeApp() as app:
    # do something with app

If you want to use a specific database or database connection, pass either the db or conn arguments. If the context manager opened a new connection, it will close it, but it will not close a connection passed with conn.

To set keys in the (fake) request environment, pass a dictionary of environment values as environ.

Note that zopeApp() should not normally be used in tests or test set-up/tear-down, because the INTEGRATOIN_TEST and FUNCTIONAL_TESTING layers both manage the application root (as the app resource) and close it for you. It is very useful in layer setup, however.

The other helper functions defined in plone.testing.zope can also be used in a ZServer context but together with the ZServer layers.

Using Layer as a base class

The usual pattern is to use Layer as a base class for a custom layer. This can then override the lifecycle methods as appropriate, as well as set a default list of bases.:

>>> class BaseLayer(Layer):
...
...     def setUp(self):
...         print("Setting up base layer")
...
...     def tearDown(self):
...         print("Tearing down base layer")

>>> BASE_LAYER = BaseLayer()

The layer name and module are taken from the class.:

>>> BASE_LAYER.__bases__
()
>>> BASE_LAYER.__name__
'BaseLayer'
>>> BASE_LAYER.__module__
'builtins'

We can now create a new layer that has this one as a base. We can do this in the instance constructor, as shown above, but the most common pattern is to set the default bases in the class body, using the variable defaultBases.

We’ll also set the default name explicitly here by passing a name to the the super-constructor. This is mostly cosmetic, but may be desirable if the class name would be misleading in the test runner output.:

>>> class ChildLayer(Layer):
...     defaultBases = (BASE_LAYER,)
...
...     def __init__(self, bases=None, name='Child layer', module=None):
...         super(ChildLayer, self).__init__(bases, name, module)
...
...     def setUp(self):
...         print("Setting up child layer")
...
...     def tearDown(self):
...         print("Tearing down child layer")

>>> CHILD_LAYER = ChildLayer()

Notice how the bases have now been set using the value in defaultBases.:

>>> CHILD_LAYER.__bases__
(<Layer 'builtins.BaseLayer'>,)
>>> CHILD_LAYER.__name__
'Child layer'
>>> CHILD_LAYER.__module__
'builtins'

Overriding the default list of bases

We can override the list of bases on a per-instance basis. This may be dangerous, i.e. the layer is likely to expect that its bases are set up. Sometimes, it may be useful to inject a new base, however, especially when re-using layers from other packages.

The new list of bases is passed to the constructor. When creating a second instance of a layer (most layers are global singletons created only once), it’s useful to give the new instance a unique name, too.:

>>> NEW_CHILD_LAYER = ChildLayer(bases=(SIMPLE_LAYER, BASE_LAYER,), name='New child')

>>> NEW_CHILD_LAYER.__bases__
(<Layer 'plone.testing.tests.Simple layer'>, <Layer 'builtins.BaseLayer'>)
>>> NEW_CHILD_LAYER.__name__
'New child'
>>> NEW_CHILD_LAYER.__module__
'builtins'

Inconsistent bases

Layer bases are maintained in an order that is semantically equivalent to the “method resolution order” Python maintains for base classes. We can get this from the baseResolutionOrder attribute::

>>> CHILD_LAYER.baseResolutionOrder
(<Layer 'builtins.Child layer'>, <Layer 'builtins.BaseLayer'>)

>>> NEW_CHILD_LAYER.baseResolutionOrder
(<Layer 'builtins.New child'>, <Layer 'plone.testing.tests.Simple layer'>,
 <Layer 'plone.testing.layer.Null layer'>,
 <Layer 'builtins.BaseLayer'>)

As with Python classes, it is possible to construct an invalid set of bases. In this case, layer instantiation will fail.:

>>> INCONSISTENT_BASE1 = Layer(name="Inconsistent 1")
>>> INCONSISTENT_BASE2 = Layer((INCONSISTENT_BASE1,), name="Inconsistent 1")
>>> INCONSISTENT_BASE3 = Layer((INCONSISTENT_BASE1, INCONSISTENT_BASE2,), name="Inconsistent 1")
Traceback (most recent call last):
...
TypeError: Inconsistent layer hierarchy!

Using the resource manager

Layers are also resource managers. Resources can be set, retrieved and deleted using dictionary syntax. Resources in base layers are available in child layers. When an item is set on a child layer, it shadows any items with the same key in any base layer (until it is deleted), but the original item still exists.

Let’s create a somewhat complex hierarchy of layers that all set resources under a key 'foo' in their setUp() methods.:

>>> class Layer1(Layer):
...     def setUp(self):
...         self['foo'] = 1
...     def tearDown(self):
...         del self['foo']
>>> LAYER1 = Layer1()

>>> class Layer2(Layer):
...     defaultBases = (LAYER1,)
...     def setUp(self):
...         self['foo'] = 2
...     def tearDown(self):
...         del self['foo']
>>> LAYER2 = Layer2()

>>> class Layer3(Layer):
...     def setUp(self):
...         self['foo'] = 3
...     def tearDown(self):
...         del self['foo']
>>> LAYER3 = Layer3()

>>> class Layer4(Layer):
...     defaultBases = (LAYER2, LAYER3,)
...     def setUp(self):
...         self['foo'] = 4
...     def tearDown(self):
...         del self['foo']
>>> LAYER4 = Layer4()

**Important:** Resources that are created in ``setUp()`` must be deleted in ``tearDown()``.
Similarly, resources created in ``testSetUp()`` must be deleted in ``testTearDown()``.
This ensures resources are properly stacked and do not leak between layers.

If a test was using LAYER4, the test runner would call each setup step in turn, starting with the “deepest” layer. We’ll simulate that here, so that each of the resources is created.:

>>> LAYER1.setUp()
>>> LAYER2.setUp()
>>> LAYER3.setUp()
>>> LAYER4.setUp()

The layers are ordered in a known “resource resolution order”, which is used to determine in which order the layers shadow one another. This is based on the same algorithm as Python’s method resolution order.:

>>> LAYER4.baseResolutionOrder
(<Layer 'builtins.Layer4'>,
 <Layer 'builtins.Layer2'>,
 <Layer 'builtins.Layer1'>,
 <Layer 'builtins.Layer3'>)

When fetching and item from a layer, it will be obtained according to the resource resolution order.:

>>> LAYER4['foo']
4

This is not terribly interesting, since LAYER4 has the resource 'foo' set directly. Let’s tear down the layer (which deletes the resource) and see what happens.:

>>> LAYER4.tearDown()
>>> LAYER4['foo']
2

We can continue up the chain::

>>> LAYER2.tearDown()
>>> LAYER4['foo']
1

>>> LAYER1.tearDown()
>>> LAYER4['foo']
3

Once we’ve deleted the last key, we’ll get a KeyError::

>>> LAYER3.tearDown()
>>> LAYER4['foo']
Traceback (most recent call last):
...
KeyError: 'foo'

To guard against this, we can use the get() method.:

>>> LAYER4.get('foo', -1)
-1

We can also test with ‘in’::

>>> 'foo' in LAYER4
False

To illustrate that this indeed works, let’s set the resource back on one of the bases.:

>>> LAYER3['foo'] = 10
>>> LAYER4.get('foo', -1)
10

Let’s now consider a special case: a base layer sets up a resource in layer setup, and uses it in test setup. A child layer then shadows this resource in its own layer setup method. In this case, we want the base layer’s testSetUp() to use the shadowed version that the child provided.

(This is similar to how instance variables work: a base class may set an attribute on self and use it in a method. If a subclass then sets the same attribute to a different value and the base class method is called on an instance of the subclass, the base class attribute is used).

Hint: If you definitely need to access the “original” resource in your testSetUp()/testTearDown() methods, you can store a reference to the resource as a layer instance variable:

self.someResource = self['someResource'] = SomeResource()

self.someResource will now be the exact resource created here, whereas self['someResource'] will retain the layer shadowing semantics. In most cases, you probably don’t want to do this, allowing child layers to supply overridden versions of resources as appropriate.

First, we’ll create some base layers. We want to demonstrate having two “branches” of bases that both happen to define the same resource.:

>>> class ResourceBaseLayer1(Layer):
...     def setUp(self):
...         self['resource'] = "Base 1"
...     def testSetUp(self):
...         print(self['resource'])
...     def tearDown(self):
...         del self['resource']

>>> RESOURCE_BASE_LAYER1 = ResourceBaseLayer1()

>>> class ResourceBaseLayer2(Layer):
...     defaultBases = (RESOURCE_BASE_LAYER1,)
...     def testSetUp(self):
...         print(self['resource'])

>>> RESOURCE_BASE_LAYER2 = ResourceBaseLayer2()

>>> class ResourceBaseLayer3(Layer):
...     def setUp(self):
...         self['resource'] = "Base 3"
...     def testSetUp(self):
...         print(self['resource'])
...     def tearDown(self):
...         del self['resource']

>>> RESOURCE_BASE_LAYER3 = ResourceBaseLayer3()

We’ll then create the child layer that overrides this resource.:

>>> class ResourceChildLayer(Layer):
...     defaultBases = (RESOURCE_BASE_LAYER2, RESOURCE_BASE_LAYER3)
...     def setUp(self):
...         self['resource'] = "Child"
...     def testSetUp(self):
...         print(self['resource'])
...     def tearDown(self):
...         del self['resource']

>>> RESOURCE_CHILD_LAYER = ResourceChildLayer()

We’ll first set up the base layers on their own and simulate two tests.

A test with RESOURCE_BASE_LAYER1 only would look like this::

>>> RESOURCE_BASE_LAYER1.setUp()

>>> RESOURCE_BASE_LAYER1.testSetUp()
Base 1
>>> RESOURCE_BASE_LAYER1.testTearDown()

>>> RESOURCE_BASE_LAYER1.tearDown()

A test with RESOURCE_BASE_LAYER2 would look like this::

>>> RESOURCE_BASE_LAYER1.setUp()
>>> RESOURCE_BASE_LAYER2.setUp()

>>> RESOURCE_BASE_LAYER1.testSetUp()
Base 1
>>> RESOURCE_BASE_LAYER2.testSetUp()
Base 1
>>> RESOURCE_BASE_LAYER2.testTearDown()
>>> RESOURCE_BASE_LAYER1.testTearDown()

>>> RESOURCE_BASE_LAYER2.tearDown()
>>> RESOURCE_BASE_LAYER1.tearDown()

A test with RESOURCE_BASE_LAYER3 only would look like this::

>>> RESOURCE_BASE_LAYER3.setUp()

>>> RESOURCE_BASE_LAYER3.testSetUp()
Base 3
>>> RESOURCE_BASE_LAYER3.testTearDown()

>>> RESOURCE_BASE_LAYER3.tearDown()

Now let’s set up the child layer and simulate another test. We should now be using the shadowed resource.:

>>> RESOURCE_BASE_LAYER1.setUp()
>>> RESOURCE_BASE_LAYER2.setUp()
>>> RESOURCE_BASE_LAYER3.setUp()
>>> RESOURCE_CHILD_LAYER.setUp()

>>> RESOURCE_BASE_LAYER1.testSetUp()
Child
>>> RESOURCE_BASE_LAYER2.testSetUp()
Child
>>> RESOURCE_BASE_LAYER3.testSetUp()
Child
>>> RESOURCE_CHILD_LAYER.testSetUp()
Child

>>> RESOURCE_CHILD_LAYER.testTearDown()
>>> RESOURCE_BASE_LAYER3.testTearDown()
>>> RESOURCE_BASE_LAYER2.testTearDown()
>>> RESOURCE_BASE_LAYER1.testTearDown()

Finally, we’ll tear down the child layer again and simulate another test. we should have the original resources back. Note that the first and third layers no longer share a resource, since they don’t have a common ancestor.:

>>> RESOURCE_CHILD_LAYER.tearDown()

>>> RESOURCE_BASE_LAYER1.testSetUp()
Base 1
>>> RESOURCE_BASE_LAYER2.testSetUp()
Base 1
>>> RESOURCE_BASE_LAYER2.testTearDown()
>>> RESOURCE_BASE_LAYER1.testTearDown()

>>> RESOURCE_BASE_LAYER3.testSetUp()
Base 3
>>> RESOURCE_BASE_LAYER3.testTearDown()

Finally, we’ll tear down the remaining layers..:

>>> RESOURCE_BASE_LAYER3.tearDown()
>>> RESOURCE_BASE_LAYER2.tearDown()
>>> RESOURCE_BASE_LAYER1.tearDown()

>>> class BadLayer1(Layer):
...     def setUp(self):
...         pass
...     def tearDown(self):
...         del self['foo']
>>> BAD_LAYER1 = BadLayer1()

>>> class BadLayer2(Layer):
...     defaultBases = (BAD_LAYER1,)
...     def setUp(self):
...         self['foo'] = 1
...         self['bar'] = 2
>>> BAD_LAYER2 = BadLayer2()

>>> BAD_LAYER1.setUp()
>>> BAD_LAYER2.setUp()

>>> BAD_LAYER1.testSetUp()
>>> BAD_LAYER2.testSetUp()

>>> BAD_LAYER2.testTearDown()
>>> BAD_LAYER1.testTearDown()

>>> BAD_LAYER2.tearDown()
>>> BAD_LAYER1.tearDown()
Traceback (most recent call last):
...
KeyError: 'foo'

>>> 'foo' in BAD_LAYER2._resources
True
>>> 'bar' in BAD_LAYER2._resources
True

Doctest layer helper

The doctest module is not aware of zope.testing’s layers concept. Therefore, the syntax for creating a doctest with a layer and adding it to a test suite is somewhat contrived: the test suite has to be created first, and then the layer attribute set on it::

>>> class DoctestLayer(Layer):
...     pass
>>> DOCTEST_LAYER = DoctestLayer()

>>> import unittest
>>> import doctest

>>> def test_suite():
...     suite = unittest.TestSuite()
...     layerDoctest = doctest.DocFileSuite('layer.rst', package='plone.testing')
...     layerDoctest.layer = DOCTEST_LAYER
...     suite.addTest(layerDoctest)
...     return suite

>>> suite = test_suite()
>>> tests = list(suite)
>>> len(tests)
1
>>> tests[0].layer is DOCTEST_LAYER
True

To make this a little easier - especially when setting up multiple tests - a helper function called layered is provided::

>>> from plone.testing import layered

>>> def test_suite():
...     suite = unittest.TestSuite()
...     suite.addTests([
...         layered(doctest.DocFileSuite('layer.rst', package='plone.testing'), layer=DOCTEST_LAYER),
...         # repeat with more suites if necessary
...     ])
...     return suite

This does the same as the sample above.:

>>> suite = test_suite()
>>> tests = list(suite)
>>> len(tests)
1
>>> tests[0].layer is DOCTEST_LAYER
True

In addition, a ‘layer’ glob is added to each test in the suite. This allows the test to access layer resources.:

>>> len(list(tests[0]))
1
>>> list(tests[0])[0]._dt_test.globs['layer'] is DOCTEST_LAYER
True

Unit testing

The UNIT_TESTING layer is used to set up a clean component registry between each test. It uses zope.testing.cleanup to clean up all global state.

It has no bases::

>>> "%s.%s" % (zca.UNIT_TESTING.__module__, zca.UNIT_TESTING.__name__,)
'plone.testing.zca.UnitTesting'

>>> zca.UNIT_TESTING.__bases__
()

The component registry is cleaned up between each test.:

>>> from zope.interface import Interface
>>> from zope.component import provideUtility

>>> class DummyUtility(object):
...     def __init__(self, name):
...         self.name = name
...     def __repr__(self):
...         return "<%s>" % self.name

>>> provideUtility(DummyUtility("Dummy"), provides=Interface, name="test-dummy")

>>> from zope.component import queryUtility
>>> queryUtility(Interface, name="test-dummy")
<Dummy>

Layer setup does nothing.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zca.UNIT_TESTING, setupLayers)
Set up plone.testing.zca.UnitTesting in ... seconds.

Let’s now simulate a test. Before any test setup has happened, our previously registered utility is still there.:

>>> queryUtility(Interface, name="test-dummy")
<Dummy>

On test setup, it disappears.:

>>> zca.UNIT_TESTING.testSetUp()

>>> queryUtility(Interface, name="test-dummy") is None
True

The test would now execute. It may register some components.:

>>> provideUtility(DummyUtility("Dummy2"), provides=Interface, name="test-dummy")
>>> queryUtility(Interface, name="test-dummy")
<Dummy2>

On test tear-down, this disappears.:

>>> zca.UNIT_TESTING.testTearDown()

>>> queryUtility(Interface, name="test-dummy") is None
True

Layer tear-down does nothing.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zca.UnitTesting in ... seconds.

Event testing

The EVENT_TESTING layer extends the UNIT_TESTING layer to add the necessary registrations for zope.component.eventtesting to work.:

>>> "%s.%s" % (zca.EVENT_TESTING.__module__, zca.EVENT_TESTING.__name__,)
'plone.testing.zca.EventTesting'

>>> zca.EVENT_TESTING.__bases__
(<Layer 'plone.testing.zca.UnitTesting'>,)

Before the test, the component registry is empty and getEvents() returns nothing, even if an event is fired.:

>>> from zope.component.eventtesting import getEvents

>>> class DummyEvent(object):
...     def __repr__(self):
...         return "<Dummy event>"

>>> from zope.event import notify
>>> notify(DummyEvent())

>>> getEvents()
[]

Layer setup does nothing.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zca.EVENT_TESTING, setupLayers)
Set up plone.testing.zca.UnitTesting in ... seconds.
Set up plone.testing.zca.EventTesting in ... seconds.

Let’s now simulate a test. On test setup, the event testing list is emptied.:

>>> zca.UNIT_TESTING.testSetUp()
>>> zca.EVENT_TESTING.testSetUp()

>>> getEvents()
[]

The test would now execute. It may fire some events, which would show up in the event testing list.:

>>> notify(DummyEvent())
>>> getEvents()
[<Dummy event>]

On test tear-down, the list is emptied again::

>>> zca.EVENT_TESTING.testTearDown()
>>> zca.UNIT_TESTING.testTearDown()

>>> getEvents()
[]

Layer tear-down does nothing.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zca.EventTesting in ... seconds.
Tear down plone.testing.zca.UnitTesting in ... seconds.

Layer cleanup

The LAYER_CLEANUP layer is used to set up a clean component registry at the set-up and tear-down of a layer. It uses zope.testing.cleanup to clean up all global state.

It has no bases::

>>> "%s.%s" % (zca.LAYER_CLEANUP.__module__, zca.LAYER_CLEANUP.__name__,)
'plone.testing.zca.LayerCleanup'

>>> zca.LAYER_CLEANUP.__bases__
()

The component registry is cleaned up on layer set-up and tear-down (but not between tests).:

>>> from zope.interface import Interface
>>> from zope.component import provideUtility

>>> class DummyUtility(object):
...     def __init__(self, name):
...         self.name = name
...     def __repr__(self):
...         return "<%s>" % self.name

>>> provideUtility(DummyUtility("Dummy"), provides=Interface, name="test-dummy")

>>> from zope.component import queryUtility
>>> queryUtility(Interface, name="test-dummy")
<Dummy>

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zca.LAYER_CLEANUP, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.

>>> queryUtility(Interface, name="test-dummy") is None
True

A sub-layer may register additional components::

>>> provideUtility(DummyUtility("Dummy2"), provides=Interface, name="test-dummy2")

Let’s now simulate a test. Test setup and tear-down does nothing.:

>>> zca.LAYER_CLEANUP.testSetUp()

>>> queryUtility(Interface, name="test-dummy") is None
True
>>> queryUtility(Interface, name="test-dummy2")
<Dummy2>

>>> zca.LAYER_CLEANUP.testTearDown()

>>> queryUtility(Interface, name="test-dummy") is None
True
>>> queryUtility(Interface, name="test-dummy2")
<Dummy2>

On tear-down, the registry is cleaned again.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zca.LayerCleanup in ... seconds.

>>> queryUtility(Interface, name="test-dummy") is None
True
>>> queryUtility(Interface, name="test-dummy2") is None
True

Basic ZCML directives

The ZCML_DIRECTIVES layer creates a ZCML configuration context with the basic zope.component directives available. It extends the LAYER_CLEANUP layer.:

>>> "%s.%s" % (zca.ZCML_DIRECTIVES.__module__, zca.ZCML_DIRECTIVES.__name__,)
'plone.testing.zca.ZCMLDirectives'

>>> zca.ZCML_DIRECTIVES.__bases__
(<Layer 'plone.testing.zca.LayerCleanup'>,)

Before the test, we cannot use e.g. a <utility /> directive without loading the necessary meta.zcml files.:

>>> from zope.configuration import xmlconfig
>>> from zope.configuration.exceptions import ConfigurationError
>>> try:
...     xmlconfig.string("""\
...     <configure package="plone.testing" xmlns="http://namespaces.zope.org/zope">
...         <utility factory=".tests.DummyUtility" provides="zope.interface.Interface" name="test-dummy" />
...     </configure>""")
... except ConfigurationError as e:
...     True
True

Layer setup creates a configuration context we can use to load further configuration.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zca.ZCML_DIRECTIVES, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zca.ZCMLDirectives in ... seconds.

Let’s now simulate a test that uses this configuration context to load the same ZCML string.:

>>> zca.ZCML_DIRECTIVES.testSetUp()

>>> context = zca.ZCML_DIRECTIVES['configurationContext'] # would normally be self.layer['configurationContext']
>>> xmlconfig.string("""\
... <configure package="plone.testing" xmlns="http://namespaces.zope.org/zope">
...     <utility factory=".tests.DummyUtility" provides="zope.interface.Interface" name="test-dummy" />
... </configure>""", context=context) is context
True

The utility is now registered::

>>> queryUtility(Interface, name="test-dummy")
<Dummy utility>

>>> zca.UNIT_TESTING.testTearDown()

Note that normally, we’d combine this with the UNIT_TESTING layer to tear down the component architecture as well.

Layer tear-down deletes the configuration context.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zca.ZCMLDirectives in ... seconds.

>>> zca.ZCML_DIRECTIVES.get('configurationContext', None) is None
True

Configuration registry sandboxing

For simple unit tests, the full cleanup performed between each test using the UNIT_TESTING layer is undoubtedly the safest and most convenient way to ensure proper isolation of tests using the global component architecture. However, if you are writing a complex layer that sets up a lot of components, you may wish to keep some components registered at the layer level, whilst still allowing tests and sub-layers to register their own components in isolation.

This is a tricky problem, because the default ZCML directives and APIs (provideAdapter(), provideUtility() and so on) explicitly work on a single global adapter registry object. To get around this, you can use two helper methods in the zca module to push a new global component registry before registering components, and pop the registry after. Registries are stacked, so the components registered in a “lower” registry are automatically available in a “higher” registry.

Let’s illustrate this with a layer that stacks two new global registries. The first registry is specific to the layer, and is used to house the components registered at the layer level. The second registry is set up and torn down for each test, allowing tests to register their own components freely.

First, we’ll create a simple dummy utility to illustrate registrations.:

>>> from zope.interface import Interface, implementer

>>> class IDummyUtility(Interface):
...     pass
>>> @implementer(IDummyUtility)
... class DummyUtility(object):
...     def __init__(self, name):
...         self.name = name
...     def __repr__(self):
...         return "<DummyUtility %s>" % self.name

The two key methods are:

• zca.pushGlobalRegistry(), which creates a new global registry.

• zca.popGlobalRegistry(), which restores the previous global registry.

  Warning: You must balance your calls to these methods. If you call pushGlobalRegistry() in setUp(), call popGlobalRegistry() in tearDown(). Ditto for testSetUp() and testTearDown().

Let’s now create our layer.:

>>> from zope.component import provideUtility
>>> from plone.testing import Layer
>>> from plone.testing import zca

>>> class ComponentSandbox(Layer):
...     def setUp(self):
...         zca.pushGlobalRegistry()
...         provideUtility(DummyUtility("layer"), name="layer")
...     def tearDown(self):
...         zca.popGlobalRegistry()
...     def testSetUp(self):
...         zca.pushGlobalRegistry()
...     def testTearDown(self):
...         zca.popGlobalRegistry()
>>> COMPONENT_SANDBOX = ComponentSandbox()

Let’s now simulate a test using this layer.

To begin with, we have the default registry.:

>>> from zope.component import getGlobalSiteManager, getSiteManager
>>> getSiteManager() is getGlobalSiteManager()
True

>>> defaultGlobalSiteManager = getGlobalSiteManager()

>>> from zope.component import queryUtility
>>> queryUtility(IDummyUtility, name="layer") is None
True

We’ll now simulate layer setup. This will push a new registry onto the stack::

>>> COMPONENT_SANDBOX.setUp()

>>> getSiteManager() is getGlobalSiteManager()
True
>>> getGlobalSiteManager() is defaultGlobalSiteManager
False
>>> layerGlobalSiteManager = getGlobalSiteManager()

>>> queryUtility(IDummyUtility, name="layer")
<DummyUtility layer>

We’ll then simulate a test that registers a global component::

>>> COMPONENT_SANDBOX.testSetUp()

>>> getSiteManager() is getGlobalSiteManager()
True
>>> getGlobalSiteManager() is defaultGlobalSiteManager
False
>>> getGlobalSiteManager() is layerGlobalSiteManager
False

Our previously registered component is still here.:

>>> queryUtility(IDummyUtility, name="layer")
<DummyUtility layer>

We can also register a new one.:

>>> provideUtility(DummyUtility("test"), name="test")
>>> queryUtility(IDummyUtility, name="layer")
<DummyUtility layer>
>>> queryUtility(IDummyUtility, name="test")
<DummyUtility test>

On test tear-down, only the second utility disappears::

>>> COMPONENT_SANDBOX.testTearDown()

>>> getSiteManager() is getGlobalSiteManager()
True
>>> getGlobalSiteManager() is defaultGlobalSiteManager
False
>>> getGlobalSiteManager() is layerGlobalSiteManager
True

>>> queryUtility(IDummyUtility, name="layer")
<DummyUtility layer>
>>> queryUtility(IDummyUtility, name="test") is None
True

If we tear down the layer too, we’re back where we started::

>>> COMPONENT_SANDBOX.tearDown()

>>> getSiteManager() is getGlobalSiteManager()
True
>>> getGlobalSiteManager() is defaultGlobalSiteManager
True

>>> queryUtility(IDummyUtility, name="layer") is None
True
>>> queryUtility(IDummyUtility, name="test") is None
True

ZCML files helper class

One of the frequent use cases is a layer that loads a ZCML file and sandbox the resulting registry.

The ZCMLSandbox can be instantiated with a filename` and package arguments.:

>>> import plone.testing
>>> ZCML_SANDBOX = zca.ZCMLSandbox(filename="testing_zca.zcml",
...     package=plone.testing)

Before layer setup, the utility is not registered.:

>>> queryUtility(Interface, name="layer") is None
True

We’ll now simulate layer setup. This pushes a new registry onto the stack::

>>> ZCML_SANDBOX.setUp()

>>> getSiteManager() is getGlobalSiteManager()
True
>>> getGlobalSiteManager() is defaultGlobalSiteManager
False
>>> queryUtility(Interface, name="layer")
<Dummy utility>

The ZCMLSandbox class can also be used as ancestor for your own classes when you need to load more than a single ZCML file.

Your class then needs to override the setUpZCMLFiles() method. It is in charge of calling loadZCMLFile(), once for each ZCML file that the class needs to load.:

>>> class OtherZCML(zca.ZCMLSandbox):
...     def setUpZCMLFiles(self):
...         self.loadZCMLFile("testing_zca.zcml", package=plone.testing)
...         self.loadZCMLFile("testing_zca_more_specific.zcml",
...             package=plone.testing)
>>> OTHER_ZCML_SANDBOX = OtherZCML()

Before layer setup, a second utility is not registered.:

>>> queryUtility(Interface, name="more_specific_layer") is None
True

We’ll now simulate the setup of the more specific layer.:

>>> OTHER_ZCML_SANDBOX.setUp()

After setUp, the second utility is registered::

>>> queryUtility(Interface, name="more_specific_layer")
<Dummy utility>

After layer teardown, the second utility is not registered anymore.:

>>> OTHER_ZCML_SANDBOX.tearDown()
>>> queryUtility(Interface, name="more_specific_layer") is None
True

After teardown of the first layer, the first utility is not registered anymore.:

>>> ZCML_SANDBOX.tearDown()
>>> queryUtility(Interface, name="layer") is None
True

Layers

The security.CHECKERS layer makes sure that zope.security checkers are correctly set up and torn down.:

>>> "%s.%s" % (security.CHECKERS.__module__, security.CHECKERS.__name__,)
'plone.testing.security.Checkers'

>>> security.CHECKERS.__bases__
()

Before the test, our custom checker is not in the registry.:

>>> class DummyObject(object):
...     pass

>>> from zope.security.interfaces import IChecker
>>> from zope.interface import implementer
>>> @implementer(IChecker)
... class FauxChecker(object):
...     # we should really implement the interface here, but oh well
...     pass

>>> from zope.security.checker import getCheckerForInstancesOf
>>> getCheckerForInstancesOf(DummyObject) is None
True

Layer setup stacks the current checkers.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, security.CHECKERS, setupLayers)
Set up plone.testing.security.Checkers in ... seconds.

We can now set up a checker. In real life, this may happen during ZCML configuration, but here will just call the API directlyMost likely, we’d do this in a child layer::

>>> from zope.security.checker import defineChecker
>>> fauxChecker = FauxChecker()
>>> defineChecker(DummyObject, fauxChecker)

>>> getCheckerForInstancesOf(DummyObject) is fauxChecker
True

Let’s now simulate a test that may use the checker.:

>>> security.CHECKERS.testSetUp()
>>> getCheckerForInstancesOf(DummyObject) is fauxChecker
True
>>> security.CHECKERS.testTearDown()

We still have the checker after test tear-down::

>>> getCheckerForInstancesOf(DummyObject) is fauxChecker
True

However, when we tear down the layer, the checker is gone::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.security.Checkers in ... seconds.

>>> getCheckerForInstancesOf(DummyObject) is None
True

ZCML directives

The publisher.PUBLISHER_DIRECTIVES layer extends the zca.ZCML_DIRECTIVES layer to extend its ZCML configuration context with the zope.app.publisher and zope.security directives available. It also extends security.CHECKERS.:

>>> from plone.testing import zca, security

>>> "%s.%s" % (publisher.PUBLISHER_DIRECTIVES.__module__, publisher.PUBLISHER_DIRECTIVES.__name__,)
'plone.testing.publisher.PublisherDirectives'

>>> publisher.PUBLISHER_DIRECTIVES.__bases__
(<Layer 'plone.testing.zca.ZCMLDirectives'>, <Layer 'plone.testing.security.Checkers'>)

Before the test, we cannot use e.g. the <permission /> or <browser:view /> directives without loading the necessary meta.zcml files.:

>>> from zope.configuration import xmlconfig
>>> from zope.configuration.exceptions import ConfigurationError
>>> try:
...     xmlconfig.string("""\
...     <configure package="plone.testing"
...         xmlns="http://namespaces.zope.org/zope"
...         xmlns:browser="http://namespaces.zope.org/browser"
...         i18n_domain="plone.testing.tests">
...         <permission id="plone.testing.Test" title="plone.testing: Test" />
...         <browser:view
...             for="*"
...             name="plone.testing-test"
...             class="plone.testing.tests.DummyView"
...             permission="zope.Public"
...             />
...     </configure>""")
... except ConfigurationError as e:
...     True
True

Layer setup creates a configuration context we can use to load further configuration.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, publisher.PUBLISHER_DIRECTIVES, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zca.ZCMLDirectives in ... seconds.
Set up plone.testing.security.Checkers in ... seconds.
Set up plone.testing.publisher.PublisherDirectives in ... seconds.

Let’s now simulate a test that uses this configuration context to load the same ZCML string.:

>>> zca.ZCML_DIRECTIVES.testSetUp()
>>> security.CHECKERS.testSetUp()
>>> publisher.PUBLISHER_DIRECTIVES.testSetUp()

>>> context = zca.ZCML_DIRECTIVES['configurationContext'] # would normally be self.layer['configurationContext']
>>> xmlconfig.string("""\
... <configure package="plone.testing"
...     xmlns="http://namespaces.zope.org/zope"
...     xmlns:browser="http://namespaces.zope.org/browser"
...     i18n_domain="plone.testing.tests">
...     <permission id="plone.testing.Test" title="plone.testing: Test" />
...     <browser:view
...         for="*"
...         name="plone.testing-test"
...         class="plone.testing.tests.DummyView"
...         permission="zope.Public"
...         />
... </configure>""", context=context) is context
True

The permission and view are now registered::

>>> from zope.component import queryUtility
>>> from zope.security.interfaces import IPermission

>>> queryUtility(IPermission, name=u"plone.testing.Test")
<zope.security.permission.Permission object at ...>

>>> from zope.interface import Interface
>>> from zope.publisher.interfaces.browser import IDefaultBrowserLayer
>>> from zope.component import getSiteManager
>>> siteManager = getSiteManager()

>>> [x.factory for x in siteManager.registeredAdapters()
...  if x.provided==Interface and x.required==(Interface, IDefaultBrowserLayer)
...   and x.name==u"plone.testing-test"]
[<class '....plone.testing-test'>]

We can then simulate test tear-down::

>>> publisher.PUBLISHER_DIRECTIVES.testTearDown()
>>> security.CHECKERS.testTearDown()
>>> zca.ZCML_DIRECTIVES.testTearDown()

Note that you’d normally combine this layer with the zca.UNIT_TESTING or a similar layer to automatically tear down the component architecture between each test. Here, we need to do it manually.:

>>> from zope.component.testing import tearDown
>>> tearDown()

Layer tear-down does nothing.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.publisher.PublisherDirectives in ... seconds.
Tear down plone.testing.zca.ZCMLDirectives in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.
Tear down plone.testing.security.Checkers in ... seconds.

>>> zca.ZCML_DIRECTIVES.get('configurationContext', None) is None
True

Empty ZODB layer

The EMPTY_ZODB layer is used to set up an empty ZODB using DemoStorage.

The storage and database are set up as layer fixtures. The database is exposed as the resource zodbDB.

A connection is opened for each test and exposed as zodbConnection. The ZODB root is also exposed, as zodbRoot. A new transaction is begun for each test. On test tear-down, the transaction is aborted, the connection is closed, and the two test-specific resources are deleted.

The layer has no bases.:

>>> "%s.%s" % (zodb.EMPTY_ZODB.__module__, zodb.EMPTY_ZODB.__name__,)
'plone.testing.zodb.EmptyZODB'

>>> zodb.EMPTY_ZODB.__bases__
()

Layer setup creates the database, but not a connection.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zodb.EMPTY_ZODB, setupLayers)
Set up plone.testing.zodb.EmptyZODB in ... seconds.

>>> db = zodb.EMPTY_ZODB['zodbDB']
>>> db.storage
EmptyZODB

>>> zodb.EMPTY_ZODB.get('zodbConnection', None) is None
True
>>> zodb.EMPTY_ZODB.get('zodbRoot', None) is None
True

Let’s now simulate a test.:

>>> zodb.EMPTY_ZODB.testSetUp()

The test would then execute. It may use the ZODB root.:

>>> zodb.EMPTY_ZODB['zodbConnection']
<Connection at ...>

>>> zodb.EMPTY_ZODB['zodbRoot']
{}

>>> zodb.EMPTY_ZODB['zodbRoot']['foo'] = 'bar'

On test tear-down, the transaction is aborted and the connection is closed.:

>>> zodb.EMPTY_ZODB.testTearDown()

>>> zodb.EMPTY_ZODB.get('zodbConnection', None) is None
True

>>> zodb.EMPTY_ZODB.get('zodbRoot', None) is None
True

The transaction has been rolled back.:

>>> conn = zodb.EMPTY_ZODB['zodbDB'].open()
>>> conn.root()
{}
>>> conn.close()

Layer tear-down closes and deletes the database.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zodb.EmptyZODB in ... seconds.

>>> zodb.EMPTY_ZODB.get('zodbDB', None) is None
True

Extending the ZODB layer

When creating a test fixture, it is often desirable to add some initial data to the database. If you want to do that once on layer setup, you can create your own layer class based on EmptyZODB and override its createStorage() and/or createDatabase() methods to return a pre-populated database.:

>>> import transaction
>>> from ZODB.DemoStorage import DemoStorage
>>> from ZODB.DB import DB

>>> class PopulatedZODB(zodb.EmptyZODB):
...
...     def createStorage(self):
...         return DemoStorage("My storage")
...
...     def createDatabase(self, storage):
...         db = DB(storage)
...         conn = db.open()
...
...         conn.root()['someData'] = 'a string'
...
...         transaction.commit()
...         conn.close()
...
...         return db

>>> POPULATED_ZODB = PopulatedZODB()

We’ll use this new layer in a similar manner to the test above, showing that the data is there for each test, but that other changes are rolled back.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, POPULATED_ZODB, setupLayers)
Set up PopulatedZODB in ... seconds.

>>> db = POPULATED_ZODB['zodbDB']
>>> db.storage
My storage

>>> POPULATED_ZODB.get('zodbConnection', None) is None
True
>>> POPULATED_ZODB.get('zodbRoot', None) is None
True

Let’s now simulate a test.:

>>> POPULATED_ZODB.testSetUp()

The test would then execute. It may use the ZODB root.:

>>> POPULATED_ZODB['zodbConnection']
<Connection at ...>

>>> POPULATED_ZODB['zodbRoot']
{'someData': 'a string'}

>>> POPULATED_ZODB['zodbRoot']['foo'] = 'bar'

On test tear-down, the transaction is aborted and the connection is closed.:

>>> POPULATED_ZODB.testTearDown()

>>> POPULATED_ZODB.get('zodbConnection', None) is None
True

>>> POPULATED_ZODB.get('zodbRoot', None) is None
True

The transaction has been rolled back.:

>>> conn = POPULATED_ZODB['zodbDB'].open()
>>> conn.root()
{'someData': 'a string'}
>>> conn.close()

Layer tear-down closes and deletes the database.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down PopulatedZODB in ... seconds.

>>> POPULATED_ZODB.get('zodbDB', None) is None
True

Stacking DemoStorage storages

The example above shows how to create a simple test fixture with a custom database. It is sometimes useful to be able to stack these fixtures, so that a base layer sets up some data for one set of tests, and a child layer extends this, temporarily, with more data.

This can be achieved using layer bases and resource shadowing, combined with ZODB’s stackable DemoStorage. There is even a helper function available::

>>> from plone.testing import Layer
>>> from plone.testing import zodb
>>> import transaction

>>> class ExpandedZODB(Layer):
...     defaultBases = (POPULATED_ZODB,)
...
...     def setUp(self):
...         # Get the database from the base layer
...
...         self['zodbDB'] = db = zodb.stackDemoStorage(self.get('zodbDB'), name='ExpandedZODB')
...
...         conn = db.open()
...         conn.root()['additionalData'] = "Some new data"
...         transaction.commit()
...         conn.close()
...
...     def tearDown(self):
...         # Close the database and delete the shadowed copy
...
...         self['zodbDB'].close()
...         del self['zodbDB']

>>> EXPANDED_ZODB = ExpandedZODB()

Notice that we are using plain Layer as a base class here. We obtain the underlying database from our bases using the resource manager, and then create a shadow copy using a stacked storage. Stacked storages contain the data of the original storage, but save changes in a separate (and, in this case, temporary) storage.

Let’s simulate a test run again to show how this would work.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, EXPANDED_ZODB, setupLayers)
Set up PopulatedZODB in ... seconds.
Set up ExpandedZODB in ... seconds.

>>> db = EXPANDED_ZODB['zodbDB']
>>> db.storage
ExpandedZODB

>>> EXPANDED_ZODB.get('zodbConnection', None) is None
True
>>> EXPANDED_ZODB.get('zodbRoot', None) is None
True

Let’s now simulate a test.:

>>> POPULATED_ZODB.testSetUp()
>>> EXPANDED_ZODB.testSetUp()

The test would then execute. It may use the ZODB root.:

>>> EXPANDED_ZODB['zodbConnection']
<Connection at ...>

>>> EXPANDED_ZODB['zodbRoot'] == dict(someData='a string', additionalData='Some new data')
True

>>> POPULATED_ZODB['zodbRoot']['foo'] = 'bar'

On test tear-down, the transaction is aborted and the connection is closed.:

>>> EXPANDED_ZODB.testTearDown()
>>> POPULATED_ZODB.testTearDown()

>>> EXPANDED_ZODB.get('zodbConnection', None) is None
True

>>> EXPANDED_ZODB.get('zodbRoot', None) is None
True

The transaction has been rolled back.:

>>> conn = EXPANDED_ZODB['zodbDB'].open()
>>> conn.root() == dict(someData='a string', additionalData='Some new data')
True
>>> conn.close()

We’ll now tear down the expanded layer and inspect the database again.:

>>> runner.tear_down_unneeded(options, [POPULATED_ZODB], setupLayers)
Tear down ExpandedZODB in ... seconds.

>>> conn = EXPANDED_ZODB['zodbDB'].open()
>>> conn.root()
{'someData': 'a string'}

>>> conn.close()

Finally, we’ll tear down the rest of the layers.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down PopulatedZODB in ... seconds.

>>> EXPANDED_ZODB.get('zodbDB', None) is None
True
>>> POPULATED_ZODB.get('zodbDB', None) is None
True

Startup

STARTUP is the base layer for all Zope WSGI testing. It sets up a Zope WSGI sandbox environment that is suitable for testing. It extends the zca.LAYER_CLEANUP layer to maximise the chances of having and leaving a pristine environment.

Note: You should probably use at least INTEGRATION_TESTING for any real test, although STARTUP is a useful base layer if you are setting up your own fixture. See the description of INTEGRATION_TESTING below.:

>>> "%s.%s" % (zope.STARTUP.__module__, zope.STARTUP.__name__,)
'plone.testing.zope.Startup'

>>> zope.STARTUP.__bases__
(<Layer 'plone.testing.zca.LayerCleanup'>,)

On layer setup, Zope is initialised in a lightweight manner. This involves certain patches to global modules that Zope manages, to reduce setup time, a database based on DemoStorage, and a minimal set of products that must be installed for Zope 2 to work. A minimal set of ZCML is loaded, but packages in the Products namespace are not automatically configured.

Let’s just verify that we have an empty component registry before the test::

>>> from zope.component import getSiteManager
>>> list(getSiteManager().registeredAdapters())
[]

Five sets a special vocabulary registry upon the layer setup, but there’s a default one set before::

>>> from zope.schema.vocabulary import getVocabularyRegistry
>>> getVocabularyRegistry()
<zope.schema.vocabulary.VocabularyRegistry object ...>

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zope.STARTUP, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zope.Startup in ... seconds.

After layer setup, the zodbDB resource is available, pointing to the default ZODB.:

>>> zope.STARTUP['zodbDB']
<ZODB.DB.DB object at ...>

>>> zope.STARTUP['zodbDB'].storage
Startup

In addition, the resources host and port are set to the default hostname and port that are used for URLs generated from Zope. These are hardcoded, but shadowed by layers that provide actual running Zope instances.:

>>> zope.STARTUP['host']
'nohost'
>>> zope.STARTUP['port']
80

At this point, it is also possible to get hold of a Zope application root. If you are setting up a layer fixture, you can obtain an application root with the correct database that is properly closed by using the zopeApp() context manager.:

>>> with zope.zopeApp() as app:
...     'acl_users' in app.objectIds()
True

If you want to use a specific database, you can pass that to zopeApp() as the db parameter. A new connection will be opened and closed.:

>>> with zope.zopeApp(db=zope.STARTUP['zodbDB']) as app:
...     'acl_users' in app.objectIds()
True

If you want to re-use an existing connection, you can pass one to zopeApp() as the connection argument. In this case, you will need to close the connection yourself.:

>>> conn = zope.STARTUP['zodbDB'].open()
>>> with zope.zopeApp(connection=conn) as app:
...     'acl_users' in app.objectIds()
True

>>> conn.opened is not None
True

>>> conn.close()

If an exception is raised within the with block, the transaction is aborted, but the connection is still closed (if it was opened by the context manager)::

>>> with zope.zopeApp() as app:
...     raise Exception("Test error")
Traceback (most recent call last):
...
Exception: Test error

It is common to combine the zopeApp() context manager with a stacked DemoStorage to set up a layer-specific fixture. As a sketch::

from plone.testing import Layer, zope, zodb

class MyLayer(Layer):
    defaultBases = (zope.STARTUP,)

    def setUp(self):
        self['zodbDB'] = zodb.stackDemoStorage(self.get('zodbDB'), name='MyLayer')
        with zope.zopeApp() as app:

            # Set up a fixture, e.g.:
            app.manage_addFolder('folder1')
            folder = app['folder1']
            folder._addRole('role1')
            folder.manage_addUserFolder()

            userFolder = folder['acl_users']
            ignore = userFolder.userFolderAddUser('user1', 'secret', ['role1'], [])
            folder.manage_role('role1', ('Access contents information',))

    def tearDown(self):
        self['zodbDB'].close()
        del self['zodbDB']

Note that you would normally not use the zope.zopeApp() in a test or in a testSetUp() or testTearDown() method. The IntegrationTesting and FunctionalTesting layer classes manage the application object for you, exposing them as the resource app (see below).

After layer setup, the global component registry contains a number of components needed by Zope.:

>>> len(list(getSiteManager().registeredAdapters())) > 1 # in fact, > a lot
True

And Five has set a Zope2VocabularyRegistry vocabulary registry::

>>> getVocabularyRegistry()
<....Zope2VocabularyRegistry object at ...>

To load additional ZCML, you can use the configurationContext resource::

>>> zope.STARTUP['configurationContext']
<zope.configuration.config.ConfigurationMachine object ...>

See zca.rst for details about how to use zope.configuration for this purpose.

The STARTUP layer does not perform any specific test setup or tear-down. That is left up to the INTEGRATION_TESTING and FUNCTIONAL_TESTING layers, or other layers using their layer classes - IntegrationTesting and FunctionalTesting.:

>>> zope.STARTUP.testSetUp()
>>> zope.STARTUP.testTearDown()

Layer tear-down resets the environment.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zope.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

>>> import Zope2
>>> Zope2._began_startup
0
>>> Zope2.DB is None
True
>>> Zope2.bobo_application is None
True

>>> list(getSiteManager().registeredAdapters())
[]

>>> getVocabularyRegistry()
<zope.schema.vocabulary.VocabularyRegistry object at ...>

Integration test

INTEGRATION_TESTING is intended for simple Zope WSGI integration testing. It extends STARTUP to ensure that a transaction is begun before and rolled back after each test. Two resources, app and request, are available during testing as well. It does not manage any layer state - it implements the test lifecycle methods only.

Note: You would normally not use INTEGRATION_TESTING as a base layer. Instead, you’d use the IntegrationTesting class to create your own layer with the testing lifecycle semantics of INTEGRATION_TESTING. See the plone.testing README file for an example.

app is the application root. In a test, you should use this instead of the zopeApp context manager (which remains the weapon of choice for setting up persistent fixtures), because the app resource is part of the transaction managed by the layer.

request is a test request. It is the same as app.REQUEST.:

>>> "%s.%s" % (zope.INTEGRATION_TESTING.__module__, zope.INTEGRATION_TESTING.__name__,)
'plone.testing.zope.IntegrationTesting'

>>> zope.INTEGRATION_TESTING.__bases__
(<Layer 'plone.testing.zope.Startup'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zope.INTEGRATION_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zope.Startup in ... seconds.
Set up plone.testing.zope.IntegrationTesting in ... seconds.

Let’s now simulate a test. On test setup, the app resource is made available. In a test, you should always use this to access the application root.:

>>> zope.STARTUP.testSetUp()
>>> zope.INTEGRATION_TESTING.testSetUp()

The test may now inspect and modify the environment.:

>>> app = zope.INTEGRATION_TESTING['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')
>>> 'acl_users' in app.objectIds() and 'folder1' in app.objectIds()
True

The request is also available::

>>> zope.INTEGRATION_TESTING['request'] # would normally be self.layer['request']
<HTTPRequest, URL=http://nohost>

We can create a user and simulate logging in as that user, using the zope.login() helper::

>>> app._addRole('role1')
>>> ignore = app['acl_users'].userFolderAddUser('user1', 'secret', ['role1'], [])
>>> zope.login(app['acl_users'], 'user1')

The first argument to zope.login() is the user folder that contains the relevant user. The second argument is the user’s name. There is no need to give the password.:

>>> from AccessControl import getSecurityManager
>>> getSecurityManager().getUser()
<User 'user1'>

You can change the roles of a user using the zope.setRoles() helper::

>>> sorted(getSecurityManager().getUser().getRolesInContext(app))
['Authenticated', 'role1']

>>> zope.setRoles(app['acl_users'], 'user1', [])
>>> getSecurityManager().getUser().getRolesInContext(app)
['Authenticated']

To become the anonymous user again, use zope.logout()::

>>> zope.logout()
>>> getSecurityManager().getUser()
<SpecialUser 'Anonymous User'>

On tear-down, the transaction is rolled back::

>>> zope.INTEGRATION_TESTING.testTearDown()
>>> zope.STARTUP.testTearDown()

>>> 'app' in zope.INTEGRATION_TESTING
False

>>> 'request' in zope.INTEGRATION_TESTING
False

>>> with zope.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

Let’s tear down the layers::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zope.IntegrationTesting in ... seconds.
Tear down plone.testing.zope.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

Functional testing

The FUNCTIONAL_TESTING layer is very similar to INTEGRATION_TESTING, and exposes the same fixture and resources. However, it has different transaction semantics. INTEGRATION_TESTING creates a single database storage, and rolls back the transaction after each test. FUNCTIONAL_TESTING creates a whole new database storage (stacked on top of the basic fixture) for each test. This allows testing of code that performs an explicit commit, which is usually required for end-to-end testing. The downside is that the set-up and tear-down of each test takes longer.

Note: Again, you would normally not use FUNCTIONAL_TESTING as a base layer. Instead, you’d use the FunctionalTesting class to create your own layer with the testing lifecycle semantics of FUNCTIONAL_TESTING. See the plone.testing README file for an example.

Like INTEGRATION_TESTING, FUNCTIONAL_TESTING is based on STARTUP.:

>>> "%s.%s" % (zope.FUNCTIONAL_TESTING.__module__, zope.FUNCTIONAL_TESTING.__name__,)
'plone.testing.zope.FunctionalTesting'

>>> zope.FUNCTIONAL_TESTING.__bases__
(<Layer 'plone.testing.zope.Startup'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zope.FUNCTIONAL_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zope.Startup in ... seconds.
Set up plone.testing.zope.FunctionalTesting in ... seconds.

Let’s now simulate a test. On test setup, the app resource is made available. In a test, you should always use this to access the application root. The request resource can be used to access the test request.:

>>> zope.STARTUP.testSetUp()
>>> zope.FUNCTIONAL_TESTING.testSetUp()

The test may now inspect and modify the environment. It may also commit things.:

>>> app = zope.FUNCTIONAL_TESTING['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')
>>> 'acl_users' in app.objectIds() and 'folder1' in app.objectIds()
True

>>> import transaction
>>> transaction.commit()

On tear-down, the database is torn down.:

>>> zope.FUNCTIONAL_TESTING.testTearDown()
>>> zope.STARTUP.testTearDown()

>>> 'app' in zope.FUNCTIONAL_TESTING
False

>>> 'request' in zope.FUNCTIONAL_TESTING
False

>>> with zope.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

Let’s tear down the layer::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zope.FunctionalTesting in ... seconds.
Tear down plone.testing.zope.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

The test browser

The FUNCTIONAL_TESTING layer and FunctionalTesting layer class are the basis for functional testing using zope.testbrowser. This simulates a web browser, allowing an application to be tested “end-to-end” via its user-facing interface.

To use the test browser with a FunctionalTesting layer (such as the default FUNCTIONAL_TESTING layer instance), we need to use a custom browser client, which ensures that the test browser uses the correct ZODB and is appropriately isolated from the test code.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zope.FUNCTIONAL_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zope.Startup in ... seconds.
Set up plone.testing.zope.FunctionalTesting in ... seconds.

Let’s simulate a test::

>>> zope.STARTUP.testSetUp()
>>> zope.FUNCTIONAL_TESTING.testSetUp()

In the test, we can create a test browser client like so::

>>> app = zope.FUNCTIONAL_TESTING['app'] # would normally be self.layer['app']
>>> browser = zope.Browser(app)

It is usually best to let Zope errors be shown with full tracebacks::

>>> browser.handleErrors = False

We can add to the test fixture in the test. For those changes to be visible to the test browser, however, we need to commit the transaction.:

>>> _ = app.manage_addDTMLDocument('dtml-doc-1')
>>> import transaction; transaction.commit()

We can now view this via the test browser::

>>> browser.open(app.absolute_url() + '/dtml-doc-1')
>>> 'This is the dtml-doc-1 Document.' in browser.contents
True

The test browser integration converts the URL into a request and passes control to Zope’s publisher. Let’s check that query strings are available for input processing::

>>> from six.moves.urllib.parse import urlencode
>>> _ = app.manage_addDTMLDocument('dtml-doc-2', file='<dtml-var foo>')
>>> import transaction; transaction.commit()
>>> qs = urlencode({'foo': 'boo, bar & baz'})  # sic: the ampersand.
>>> browser.open(app.absolute_url() + '/dtml-doc-2?' + qs)
>>> browser.contents
'boo, bar & baz'

The test browser also works with iterators. Let’s test that with a simple file implementation that uses an iterator.:

>>> from plone.testing.tests import DummyFile
>>> app._setObject('file1', DummyFile('file1'))
'file1'

>>> import transaction; transaction.commit()

>>> browser.open(app.absolute_url() + '/file1')
>>> 'The test browser also works with iterators' in browser.contents
True

See the zope.testbrowser documentation for more information about how to use the browser client.

On tear-down, the database is torn down.:

>>> zope.FUNCTIONAL_TESTING.testTearDown()
>>> zope.STARTUP.testTearDown()

>>> 'app' in zope.FUNCTIONAL_TESTING
False

>>> 'request' in zope.FUNCTIONAL_TESTING
False

>>> with zope.zopeApp() as app:
...     'acl_users' in app.objectIds()\
...         and 'folder1' not in app.objectIds()\
...         and 'file1' not in app.objectIds()
True

Let’s tear down the layer::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zope.FunctionalTesting in ... seconds.
Tear down plone.testing.zope.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

HTTP server

The WSGI_SERVER_FIXTURE layer extends STARTUP to start a single-threaded Zope server in a separate thread. This makes it possible to connect to the test instance using a web browser or a testing tool like Selenium or Windmill.

The WSGI_SERVER layer provides a FunctionalTesting layer that has WSGI_SERVER_FIXTURE as its base.:

>>> "%s.%s" % (zope.WSGI_SERVER_FIXTURE.__module__, zope.WSGI_SERVER_FIXTURE.__name__,)
'plone.testing.zope.WSGIServer'

>>> zope.WSGI_SERVER_FIXTURE.__bases__
(<Layer 'plone.testing.zope.Startup'>,)


>>> "%s.%s" % (zope.WSGI_SERVER.__module__, zope.WSGI_SERVER.__name__,)
'plone.testing.zope.WSGIServer:Functional'

>>> zope.WSGI_SERVER.__bases__
(<Layer 'plone.testing.zope.WSGIServer'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zope.WSGI_SERVER, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zope.Startup in ... seconds.
Set up plone.testing.zope.WSGIServer in ... seconds.
Set up plone.testing.zope.WSGIServer:Functional in ... seconds.

After layer setup, the resources host and port are available, and indicate where Zope is running.:

>>> host = zope.WSGI_SERVER['host']
>>> host
'localhost'

>>> port = zope.WSGI_SERVER['port']

Let’s now simulate a test. Test setup does nothing beyond what the base layers do.:

>>> zope.STARTUP.testSetUp()
>>> zope.FUNCTIONAL_TESTING.testSetUp()
>>> zope.WSGI_SERVER.testSetUp()

It is common in a test to use the Python API to change the state of the server (e.g. create some content or change a setting) and then use the HTTP protocol to look at the results. Bear in mind that the server is running in a separate thread, with a separate security manager, so calls to zope.login() and zope.logout(), for instance, do not affect the server thread.:

>>> app = zope.WSGI_SERVER['app'] # would normally be self.layer['app']
>>> _ = app.manage_addDTMLDocument('dtml-doc-3')

Note that we need to commit the transaction before it will show up in the other thread.:

>>> import transaction; transaction.commit()

We can now look for this new object through the server.:

>>> app_url = app.absolute_url()
>>> app_url.split(':')[:-1]
['http', '//localhost']

>>> from six.moves.urllib.request import urlopen
>>> conn = urlopen(app_url + '/dtml-doc-3', timeout=5)
>>> b'This is the dtml-doc-3 Document.' in conn.read()
True
>>> conn.close()

Test tear-down does nothing beyond what the base layers do.:

>>> zope.WSGI_SERVER.testTearDown()
>>> zope.FUNCTIONAL_TESTING.testTearDown()
>>> zope.STARTUP.testTearDown()

>>> 'app' in zope.WSGI_SERVER
False

>>> 'request' in zope.WSGI_SERVER
False

>>> with zope.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

When the server is torn down, the WSGIServer thread is stopped.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zope.WSGIServer:Functional in ... seconds.
Tear down plone.testing.zope.WSGIServer in ... seconds.
Tear down plone.testing.zope.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

We can expect one of these exceptions: - URLError: <urlopen error [Errno …] Connection refused> - error: [Errno 104] Connection reset by peer

>>> try:
...     conn = urlopen(app_url + '/folder1', timeout=5)
... except Exception as exc:
...     if 'Connection refused' not in str(exc) and 'Connection reset' not in str(exc):
...         raise exc
... else:
...     print('urlopen should have raised exception')

Startup

STARTUP is the base layer for all Zope 2 testing. It sets up a Zope 2 sandbox environment that is suitable for testing. It extends the zca.LAYER_CLEANUP layer to maximise the chances of having and leaving a pristine environment.

Note: You should probably use at least INTEGRATION_TESTING for any real test, although STARTUP is a useful base layer if you are setting up your own fixture. See the description of INTEGRATION_TESTING below.:

>>> "%s.%s" % (zserver.STARTUP.__module__, zserver.STARTUP.__name__,)
'plone.testing.zserver.Startup'

>>> zserver.STARTUP.__bases__
(<Layer 'plone.testing.zca.LayerCleanup'>,)

On layer setup, Zope is initialised in a lightweight manner. This involves certain patches to global modules that Zope manages, to reduce setup time, a database based on DemoStorage, and a minimal set of products that must be installed for Zope 2 to work. A minimal set of ZCML is loaded, but packages in the Products namespace are not automatically configured.

Let’s just verify that we have an empty component registry before the test::

>>> from zope.component import getSiteManager
>>> list(getSiteManager().registeredAdapters())
[]

Five sets a special vocabulary registry upon the layer setup, but there’s a default one set before::

>>> from zope.schema.vocabulary import getVocabularyRegistry
>>> getVocabularyRegistry()
<zope.schema.vocabulary.VocabularyRegistry object ...>

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.STARTUP, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.

After layer setup, the zodbDB resource is available, pointing to the default ZODB.:

>>> zserver.STARTUP['zodbDB']
<ZODB.DB.DB object at ...>

>>> zserver.STARTUP['zodbDB'].storage
Startup

In addition, the resources host and port are set to the default hostname and port that are used for URLs generated from Zope. These are hardcoded, but shadowed by layers that provide actual running Zope instances.:

>>> zserver.STARTUP['host']
'nohost'
>>> zserver.STARTUP['port']
80

At this point, it is also possible to get hold of a Zope application root. If you are setting up a layer fixture, you can obtain an application root with the correct database that is properly closed by using the zopeApp() context manager.:

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds()
True

If you want to use a specific database, you can pass that to zopeApp() as the db parameter. A new connection will be opened and closed.:

>>> with zserver.zopeApp(db=zserver.STARTUP['zodbDB']) as app:
...     'acl_users' in app.objectIds()
True

If you want to re-use an existing connection, you can pass one to zopeApp() as the connection argument. In this case, you will need to close the connection yourself.:

>>> conn = zserver.STARTUP['zodbDB'].open()
>>> with zserver.zopeApp(connection=conn) as app:
...     'acl_users' in app.objectIds()
True

>>> conn.opened is not None
True

>>> conn.close()

If an exception is raised within the with block, the transaction is aborted, but the connection is still closed (if it was opened by the context manager)::

>>> with zserver.zopeApp() as app:
...     raise Exception("Test error")
Traceback (most recent call last):
...
Exception: Test error

It is common to combine the zopeApp() context manager with a stacked DemoStorage to set up a layer-specific fixture. As a sketch::

from plone.testing import Layer, zserver, zodb

class MyLayer(Layer):
    defaultBases = (zserver.STARTUP,)

    def setUp(self):
        self['zodbDB'] = zodb.stackDemoStorage(self.get('zodbDB'), name='MyLayer')
        with zserver.zopeApp() as app:

            # Set up a fixture, e.g.:
            app.manage_addFolder('folder1')
            folder = app['folder1']
            folder._addRole('role1')
            folder.manage_addUserFolder()

            userFolder = folder['acl_users']
            ignore = userFolder.userFolderAddUser('user1', 'secret', ['role1'], [])
            folder.manage_role('role1', ('Access contents information',))

    def tearDown(self):
        self['zodbDB'].close()
        del self['zodbDB']

Note that you would normally not use the zserver.zopeApp() in a test or in a testSetUp() or testTearDown() method. The IntegrationTesting and FunctionalTesting layer classes manage the application object for you, exposing them as the resource app (see below).

After layer setup, the global component registry contains a number of components needed by Zope.:

>>> len(list(getSiteManager().registeredAdapters())) > 1 # in fact, > a lot
True

And Five has set a Zope2VocabularyRegistry vocabulary registry::

>>> getVocabularyRegistry()
<....Zope2VocabularyRegistry object at ...>

To load additional ZCML, you can use the configurationContext resource::

>>> zserver.STARTUP['configurationContext']
<zope.configuration.config.ConfigurationMachine object ...>

See zca.rst for details about how to use zope.configuration for this purpose.

The STARTUP layer does not perform any specific test setup or tear-down. That is left up to the INTEGRATION_TESTING and FUNCTIONAL_TESTING layers, or other layers using their layer classes - IntegrationTesting and FunctionalTesting.:

>>> zserver.STARTUP.testSetUp()
>>> zserver.STARTUP.testTearDown()

Layer tear-down resets the environment.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

>>> import ZServer.Zope2
>>> ZServer.Zope2._began_startup
0
>>> import Zope2
>>> Zope2.DB is None
True
>>> Zope2.bobo_application is None
True

>>> list(getSiteManager().registeredAdapters())
[]

>>> getVocabularyRegistry()
<zope.schema.vocabulary.VocabularyRegistry object at ...>

Integration test

INTEGRATION_TESTING is intended for simple Zope 2 integration testing. It extends STARTUP to ensure that a transaction is begun before and rolled back after each test. Two resources, app and request, are available during testing as well. It does not manage any layer state - it implements the test lifecycle methods only.

Note: You would normally not use INTEGRATION_TESTING as a base layer. Instead, you’d use the IntegrationTesting class to create your own layer with the testing lifecycle semantics of INTEGRATION_TESTING. See the plone.testing README file for an example.

app is the application root. In a test, you should use this instead of the zopeApp context manager (which remains the weapon of choice for setting up persistent fixtures), because the app resource is part of the transaction managed by the layer.

request is a test request. It is the same as app.REQUEST.:

>>> "%s.%s" % (zserver.INTEGRATION_TESTING.__module__, zserver.INTEGRATION_TESTING.__name__,)
'plone.testing.zserver.IntegrationTesting'

>>> zserver.INTEGRATION_TESTING.__bases__
(<Layer 'plone.testing.zserver.Startup'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.INTEGRATION_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.
Set up plone.testing.zserver.IntegrationTesting in ... seconds.

Let’s now simulate a test. On test setup, the app resource is made available. In a test, you should always use this to access the application root.:

>>> zserver.STARTUP.testSetUp()
>>> zserver.INTEGRATION_TESTING.testSetUp()

The test may now inspect and modify the environment.:

>>> app = zserver.INTEGRATION_TESTING['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')
>>> 'acl_users' in app.objectIds() and 'folder1' in app.objectIds()
True

The request is also available::

>>> zserver.INTEGRATION_TESTING['request'] # would normally be self.layer['request']
<HTTPRequest, URL=http://nohost>

We can create a user and simulate logging in as that user, using the zserver.login() helper::

>>> app._addRole('role1')
>>> ignore = app['acl_users'].userFolderAddUser('user1', 'secret', ['role1'], [])
>>> zserver.login(app['acl_users'], 'user1')

The first argument to zserver.login() is the user folder that contains the relevant user. The second argument is the user’s name. There is no need to give the password.:

>>> from AccessControl import getSecurityManager
>>> getSecurityManager().getUser()
<User 'user1'>

You can change the roles of a user using the zserver.setRoles() helper::

>>> sorted(getSecurityManager().getUser().getRolesInContext(app))
['Authenticated', 'role1']

>>> zserver.setRoles(app['acl_users'], 'user1', [])
>>> getSecurityManager().getUser().getRolesInContext(app)
['Authenticated']

To become the anonymous user again, use zserver.logout()::

>>> zserver.logout()
>>> getSecurityManager().getUser()
<SpecialUser 'Anonymous User'>

On tear-down, the transaction is rolled back::

>>> zserver.INTEGRATION_TESTING.testTearDown()
>>> zserver.STARTUP.testTearDown()

>>> 'app' in zserver.INTEGRATION_TESTING
False

>>> 'request' in zserver.INTEGRATION_TESTING
False

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

Let’s tear down the layers::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.IntegrationTesting in ... seconds.
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

Functional testing

The FUNCTIONAL_TESTING layer is very similar to INTEGRATION_TESTING, and exposes the same fixture and resources. However, it has different transaction semantics. INTEGRATION_TESTING creates a single database storage, and rolls back the transaction after each test. FUNCTIONAL_TESTING creates a whole new database storage (stacked on top of the basic fixture) for each test. This allows testing of code that performs an explicit commit, which is usually required for end-to-end testing. The downside is that the set-up and tear-down of each test takes longer.

Note: Again, you would normally not use FUNCTIONAL_TESTING as a base layer. Instead, you’d use the FunctionalTesting class to create your own layer with the testing lifecycle semantics of FUNCTIONAL_TESTING. See the plone.testing README file for an example.

Like INTEGRATION_TESTING, FUNCTIONAL_TESTING is based on STARTUP.:

>>> "%s.%s" % (zserver.FUNCTIONAL_TESTING.__module__, zserver.FUNCTIONAL_TESTING.__name__,)
'plone.testing.zserver.FunctionalTesting'

>>> zserver.FUNCTIONAL_TESTING.__bases__
(<Layer 'plone.testing.zserver.Startup'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.FUNCTIONAL_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.
Set up plone.testing.zserver.FunctionalTesting in ... seconds.

Let’s now simulate a test. On test setup, the app resource is made available. In a test, you should always use this to access the application root. The request resource can be used to access the test request.:

>>> zserver.STARTUP.testSetUp()
>>> zserver.FUNCTIONAL_TESTING.testSetUp()

The test may now inspect and modify the environment. It may also commit things.:

>>> app = zserver.FUNCTIONAL_TESTING['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')
>>> 'acl_users' in app.objectIds() and 'folder1' in app.objectIds()
True

>>> import transaction
>>> transaction.commit()

On tear-down, the database is torn down.:

>>> zserver.FUNCTIONAL_TESTING.testTearDown()
>>> zserver.STARTUP.testTearDown()

>>> 'app' in zserver.FUNCTIONAL_TESTING
False

>>> 'request' in zserver.FUNCTIONAL_TESTING
False

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

Let’s tear down the layer::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.FunctionalTesting in ... seconds.
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

The test browser

The FUNCTIONAL_TESTING layer and FunctionalTesting layer class are the basis for functional testing using zope.testbrowser. This simulates a web browser, allowing an application to be tested “end-to-end” via its user-facing interface.

To use the test browser with a FunctionalTesting layer (such as the default FUNCTIONAL_TESTING layer instance), we need to use a custom browser client, which ensures that the test browser uses the correct ZODB and is appropriately isolated from the test code.:

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.FUNCTIONAL_TESTING, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.
Set up plone.testing.zserver.FunctionalTesting in ... seconds.

Let’s simulate a test::

>>> zserver.STARTUP.testSetUp()
>>> zserver.FUNCTIONAL_TESTING.testSetUp()

In the test, we can create a test browser client like so::

>>> app = zserver.FUNCTIONAL_TESTING['app'] # would normally be self.layer['app']
>>> browser = zserver.Browser(app)

It is usually best to let Zope errors be shown with full tracebacks::

>>> browser.handleErrors = False

We can add to the test fixture in the test. For those changes to be visible to the test browser, however, we need to commit the transaction.:

>>> app.manage_addFolder('folder1')
>>> import transaction; transaction.commit()

We can now view this via the test browser::

>>> browser.open(app.absolute_url() + '/folder1')

>>> browser.contents.replace('"', '').replace("'", "")
'<Folder ...'

The __repr__ of Zope objects is not stable anymore.

The test browser integration converts the URL into a request and passes control to Zope’s publisher. Let’s check that query strings are available for input processing::

>>> import urllib
>>> qs = urllib.urlencode({'foo': 'boo, bar & baz'})  # sic: the ampersand.
>>> _ = app['folder1'].addDTMLMethod('index_html', file='<dtml-var foo>')
>>> import transaction; transaction.commit()
>>> browser.open(app.absolute_url() + '/folder1?' + qs)
>>> browser.contents
'boo, bar & baz'

The test browser also works with iterators. Let’s test that with a simple file implementation that uses an iterator.:

>>> from plone.testing.tests import DummyFile
>>> app._setObject('file1', DummyFile('file1'))
'file1'

>>> import transaction; transaction.commit()

>>> browser.open(app.absolute_url() + '/file1')
>>> 'The test browser also works with iterators' in browser.contents
True

See the zope.testbrowser documentation for more information about how to use the browser client.

On tear-down, the database is torn down.:

>>> zserver.FUNCTIONAL_TESTING.testTearDown()
>>> zserver.STARTUP.testTearDown()

>>> 'app' in zserver.FUNCTIONAL_TESTING
False

>>> 'request' in zserver.FUNCTIONAL_TESTING
False

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds()\
...         and 'folder1' not in app.objectIds()\
...         and 'file1' not in app.objectIds()
True

Let’s tear down the layer::

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.FunctionalTesting in ... seconds.
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

HTTP server

The ZSERVER_FIXTURE layer extends STARTUP to start a single-threaded Zope server in a separate thread. This makes it possible to connect to the test instance using a web browser or a testing tool like Selenium or Windmill.

The ZSERVER layer provides a FunctionalTesting layer that has ZSERVER_FIXTURE as its base.:

>>> "%s.%s" % (zserver.ZSERVER_FIXTURE.__module__, zserver.ZSERVER_FIXTURE.__name__,)
'plone.testing.zserver.ZServer'

>>> zserver.ZSERVER_FIXTURE.__bases__
(<Layer 'plone.testing.zserver.Startup'>,)


>>> "%s.%s" % (zserver.ZSERVER.__module__, zserver.ZSERVER.__name__,)
'plone.testing.zserver.ZServer:Functional'

>>> zserver.ZSERVER.__bases__
(<Layer 'plone.testing.zserver.ZServer'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.ZSERVER, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.
Set up plone.testing.zserver.ZServer in ... seconds.
Set up plone.testing.zserver.ZServer:Functional in ... seconds.

After layer setup, the resources host and port are available, and indicate where Zope is running.:

>>> host = zserver.ZSERVER['host']
>>> port = zserver.ZSERVER['port']

Let’s now simulate a test. Test setup does nothing beyond what the base layers do.:

>>> zserver.STARTUP.testSetUp()
>>> zserver.FUNCTIONAL_TESTING.testSetUp()
>>> zserver.ZSERVER.testSetUp()

It is common in a test to use the Python API to change the state of the server (e.g. create some content or change a setting) and then use the HTTP protocol to look at the results. Bear in mind that the server is running in a separate thread, with a separate security manager, so calls to zserver.login() and zserver.logout(), for instance, do not affect the server thread.:

>>> app = zserver.ZSERVER['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')

Note that we need to commit the transaction before it will show up in the other thread.:

>>> import transaction; transaction.commit()

We can now look for this new object through the server.:

>>> app_url = app.absolute_url()
>>> app_url.split(':')[:-1]
['http', '//localhost']

>>> import urllib2
>>> conn = urllib2.urlopen(app_url + '/folder1', timeout=5)
>>> conn.read().replace('"', '').replace("'", "")
'<Folder ...'
>>> conn.close()

The __repr__ of Zope objects is not stable anymore.

Test tear-down does nothing beyond what the base layers do.:

>>> zserver.ZSERVER.testTearDown()
>>> zserver.FUNCTIONAL_TESTING.testTearDown()
>>> zserver.STARTUP.testTearDown()

>>> 'app' in zserver.ZSERVER
False

>>> 'request' in zserver.ZSERVER
False

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

When the server is torn down, the ZServer thread is stopped.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.ZServer:Functional in ... seconds.
Tear down plone.testing.zserver.ZServer in ... seconds.
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

We can expect one of these exceptions: - URLError: <urlopen error [Errno …] Connection refused> - error: [Errno 104] Connection reset by peer

>>> try:
...     conn = urllib2.urlopen(app_url + '/folder1', timeout=5)
... except Exception as exc:
...     if 'Connection refused' not in str(exc) and 'Connection reset' not in str(exc):
...         raise exc
... else:
...     print('urllib2.urlopen should have raised exception')

FTP server

The FTP_SERVER layer is identical similar to ZSERVER, except that it starts an FTP server instead of an HTTP server. The fixture is contained in the FTP_SERVER_FIXTURE layer.

Warning: It is generally not safe to run the ZSERVER and FTP_SERVER layers concurrently, because they both start up the same asyncore loop. If you need concurrent HTTP and FTP servers in a test, you can create your own layer by subclassing the ZServer layer class, and overriding the setUpServer() and tearDownServer() hooks to set up and close both servers. See the code for an example.

The FTP_SERVER_FIXTURE layer is based on the STARTUP layer.:

>>> "%s.%s" % (zserver.FTP_SERVER_FIXTURE.__module__, zserver.FTP_SERVER_FIXTURE.__name__,)
'plone.testing.zserver.FTPServer'

>>> zserver.FTP_SERVER_FIXTURE.__bases__
(<Layer 'plone.testing.zserver.Startup'>,)

The FTP_SERVER layer is based on FTP_SERVER_FIXTURE, using the FunctionalTesting layer class.:

>>> "%s.%s" % (zserver.FTP_SERVER.__module__, zserver.FTP_SERVER.__name__,)
'plone.testing.zserver.FTPServer:Functional'

>>> zserver.FTP_SERVER.__bases__
(<Layer 'plone.testing.zserver.FTPServer'>,)

>>> options = runner.get_options([], [])
>>> setupLayers = {}
>>> runner.setup_layer(options, zserver.FTP_SERVER, setupLayers)
Set up plone.testing.zca.LayerCleanup in ... seconds.
Set up plone.testing.zserver.Startup in ... seconds.
Set up plone.testing.zserver.FTPServer in ... seconds.
Set up plone.testing.zserver.FTPServer:Functional in ... seconds.

After layer setup, the resources host and port are available, and indicate where Zope is running.:

>>> host = zserver.FTP_SERVER['host']
>>> port = zserver.FTP_SERVER['port']

Let’s now simulate a test. Test setup does nothing beyond what the base layers do.:

>>> zserver.STARTUP.testSetUp()
>>> zserver.FUNCTIONAL_TESTING.testSetUp()
>>> zserver.FTP_SERVER.testSetUp()

As with ZSERVER, we will set up some content for the test and then access it over the FTP port.:

>>> app = zserver.FTP_SERVER['app'] # would normally be self.layer['app']
>>> app.manage_addFolder('folder1')

We’ll also create a user in the root user folder to make FTP access easier.:

>>> ignore = app['acl_users'].userFolderAddUser('admin', 'secret', ['Manager'], ())

Note that we need to commit the transaction before it will show up in the other thread.:

>>> import transaction; transaction.commit()

We can now look for this new object through the server.:

>>> app_path = app.absolute_url_path()

>>> import ftplib
>>> ftpClient = ftplib.FTP()
>>> ftpClient.connect(host, port, timeout=5)
'220 ... FTP server (...) ready.'

>>> ftpClient.login('admin', 'secret')
'230 Login successful.'

>>> ftpClient.cwd(app_path)
'250 CWD command successful.'

>>> ftpClient.retrlines('LIST')
drwxrwx---   1 Zope     Zope            0 ... .
...--w--w----   1 Zope     Zope            0 ... acl_users
drwxrwx---   1 Zope     Zope            0 ... folder1
'226 Transfer complete'

>>> ftpClient.quit()
'221 Goodbye.'

Test tear-down does nothing beyond what the base layers do.:

>>> zserver.FTP_SERVER.testTearDown()
>>> zserver.FUNCTIONAL_TESTING.testTearDown()
>>> zserver.STARTUP.testTearDown()

>>> 'app' in zserver.ZSERVER
False

>>> 'request' in zserver.ZSERVER
False

>>> with zserver.zopeApp() as app:
...     'acl_users' in app.objectIds() and 'folder1' not in app.objectIds()
True

When the server is torn down, the FTP thread is stopped.:

>>> runner.tear_down_unneeded(options, [], setupLayers)
Tear down plone.testing.zserver.FTPServer:Functional in ... seconds.
Tear down plone.testing.zserver.FTPServer in ... seconds.
Tear down plone.testing.zserver.Startup in ... seconds.
Tear down plone.testing.zca.LayerCleanup in ... seconds.

>>> ftpClient.connect(host, port, timeout=5)
Traceback (most recent call last):
...
error: [Errno ...] Connection refused