testresources 0.2.2

Testresources, a pyunit extension for managing expensive test resources

testresources: extensions to python unittest to allow declaritive use of resources by test cases.

Copyright (C) 2005-2008 Robert Collins <[e-mail]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

testresources is attempting to extend unittest with a clean and simple api to provide test optimisation where expensive common resources are needed for test cases - for example sample working trees for VCS systems, reference databases for enterprise applications, or web servers … let imagination run wild.

Dependencies:

• Python 2.4+

• testtools

Note that testtools is required for running the tests for testresources. You can use testresources in your own app without using testtools.

How testresources works:

These are the main components to make testresources work:

1. testresources.TestResource

A TestResource is an object that tests can use. Usually a subclass of testresources.TestResource, with the getResource method overridden. This method should return an object providing the resource that the client needs (which can Optionally, the clean() method can be overridden if the resource needs to take action to clean up external resources (e.g. threads, disk files, …). The ‘resources’ list on the TestResource object is used to declare dependencies. For instance, a DataBaseResource that needs a TemporaryDirectory might be declared with a resources list:

class DataBaseResource(TestResource):

    resources = [("scratchdir", TemporaryDirectoryResource())]

Most importantly, two getResources to the same TestResource with no finishedWith call in the middle, will return the same object as long as it has not been marked dirty.

The goals for TestResources that cannot finish properly are not yet clear, so for now the behaviour will to silently continue.

A sample TestResource can be found in the doc/ folder.

See pydoc testresources.TestResource for details.

2. testresources.OptimisingTestSuite

This TestSuite will introspect all the test cases it holds directly and if they declare needed resources, will run the tests in an order that attempts to minimise the number of setup and tear downs required. It attempts to achieve this by callling getResource() and finishedWith() around the sequence of tests that use a specific resource.

Tests are added to an OptimisingTestSuite as normal. Any standard library TestSuite objects will be flattened, while any custom TestSuite subclasses will be distributed across their member tests. This means that any custom logic in test suites should be preserved, at the price of some level of optimisation.

Because the test suite does the optimisation, you can control the amount of optimising that takes place by adding more or fewer tests to a single OptimisingTestSuite. You could add everything to a single OptimisingTestSuite, getting global optimisation or you could use several smaller OptimisingTestSuites.

3. testresources.ResourcedTestCase

ResourceTestCase can be used as a base class for tests, and when that is done tests will have their resources attribute automatically checked for resources by both OptimisingTestSuite and their own setUp() and tearDown() methods. (This allows tests to remain functional without needing this specific TestSuite as a container). Alternatively, you can call ResourceTestCase.setUpResources(self) and ResourceTestCase.tearDownResources(self) from your own classes setUp and tearDown and the same behaviour will be activated.

To declare the use of a resource, set resources as an attribute listing tuples of (attribute name, TestResource). During setUp, self._attribute_name will be set to TestResource.getResource(), and finishedWith() will be called for you during tearDown().

4. testresources.TestLoader

This is a trivial TestLoader that creates OptimisingTestSuites by default.

5. unittest.TestResult

testresources will log activity about resource creation and destruction to the result object tests are run with. 4 extension methods are looked for: startCleanResource, stopCleanResource, startMakeResource, stopMakeResource. testresources.tests.ResultWithResourceExtensions is an example of a TestResult with these methods present.