« back to all changes in this revision
Viewing changes to PKG-INFO
- browse files at revision 12
- compare with another revision
- download diff
- download tarball
- view history from revision 12
- Committer: Bazaar Package Importer
- Author(s): Robert Collins
- Date: 2010-02-27 10:04:22 UTC
- mfrom: (1.1.5 upstream) (2.1.6 sid)
- Revision ID: james.westby@ubuntu.com-20100227100422-lt9yiszrs23wl8r3
Tags: 0.2.4-1
New upstream release.
- files added:
- Apache-2.0
- files modified:
- COPYING
added
removed
PKG-INFO
1
1
Metadata-Version: 1.0
2
2
Name: testresources
3
Version: 0.2.3
3
Version: 0.2.4
4
4
Summary: Testresources, a pyunit extension for managing expensive test resources
5
5
Home-page: https://launchpad.net/testresources
6
Author: Test Resources developers
6
Author: Testresources developers
7
7
Author-email: https://launchpad.net/~testresources-developers
8
8
License: UNKNOWN
9
Description: UNKNOWN
9
Description: testresources: extensions to python unittest to allow declarative use
10
of resources by test cases.
11
12
Copyright (C) 2005-2010 Robert Collins <robertc@robertcollins.net>
13
14
Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
15
license at the users choice. A copy of both licenses are available in the
16
project source as Apache-2.0 and BSD. You may not use this file except in
17
compliance with one of these two licences.
18
19
Unless required by applicable law or agreed to in writing, software
20
distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
21
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
22
license you chose for the specific language governing permissions and
23
limitations under that license.
24
25
See the COPYING file for full details on the licensing of Testresources.
26
27
28
Testresources
29
+++++++++++++
30
31
testresources is attempting to extend unittest with a clean and simple api to
32
provide test optimisation where expensive common resources are needed for test
33
cases - for example sample working trees for VCS systems, reference databases
34
for enterprise applications, or web servers ... let imagination run wild.
35
36
Dependencies
37
============
38
39
* Python 2.4+
40
* testtools
41
42
Note that testtools is required for *running* the tests for testresources. You
43
can use testresources in your own app without using testtools.
44
45
46
How testresources Works
47
=======================
48
49
The basic idea of testresources is:
50
51
* Tests declare the resources they need in a ``resources`` attribute.
52
* When the test is run, the required resource objects are allocated (either
53
newly constructed, or reused), and assigned to attributes of the TestCase.
54
55
testresources distinguishes a 'resource manager' (a subclass of
56
``TestResourceManager``) which acts as a kind of factory, and a 'resource'
57
which can be any kind of object returned from the manager class's
58
``getResource`` method.
59
60
Resources are either clean or dirty. Being clean means they have same state in
61
all important ways as a newly constructed instance and they can therefore be
62
safely reused.
63
64
Main Classes
65
============
66
67
testresources.ResourcedTestCase
68
-------------------------------
69
70
By extending or mixing-in this class, tests can have necessary resources
71
automatically allocated and disposed or recycled.
72
73
ResourceTestCase can be used as a base class for tests, and when that is done
74
tests will have their ``resources`` attribute automatically checked for
75
resources by both OptimisingTestSuite and their own setUp() and tearDown()
76
methods. (This allows tests to remain functional without needing this specific
77
TestSuite as a container). Alternatively, you can call setUpResources(self,
78
resources, test_result) and tearDownResources(self, resources, test_result)
79
from your own classes setUp and tearDown and the same behaviour will be
80
activated.
81
82
To declare the use of a resource, set the ``resources`` attribute to a list of
83
tuples of ``(attribute_name, resource_factory)``.
84
85
During setUp, for each declared requirement, the test gains an attribute
86
pointing to an allocated resource, which is the result of calling
87
``resource_factory.getResource()``. ``finishedWith`` will be called on each
88
resource during tearDown().
89
90
For example::
91
92
class TestLog(testresources.TestCase):
93
94
resources = [('branch', BzrPopulatedBranch())]
95
96
def test_log(self):
97
show_log(self.branch, ...)
98
99
testresources.TestResourceManager
100
---------------------------------
101
102
A TestResourceManager is an object that tests can use to create resources. It
103
can be overridden to manage different types of resources. Normally test code
104
doesn't need to call any methods on it, as this will be arranged by the
105
testresources machinery.
106
107
When implementing a new ``TestResourceManager`` subclass you should consider
108
overriding these methods:
109
110
``make``
111
Must be overridden in every concrete subclass.
112
113
Returns a new instance of the resource object
114
(the actual resource, not the TestResourceManager). Doesn't need to worry about
115
reuse, which is taken care of separately. This method is only called when a
116
new resource is definitely needed.
117
118
``clean``
119
Cleans up an existing resource instance, eg by deleting a directory or
120
closing a network connection. By default this does nothing, which may be
121
appropriate for resources that are automatically garbage collected.
122
123
``reset``
124
Reset a no-longer-used dirty resource to a clean state. By default this
125
just discards it and creates a new one, but for some resources there may be a
126
faster way to reset them.
127
128
``isDirty``
129
Check whether an existing resource is dirty. By default this just reports whether
130
``TestResourceManager.dirtied`` has been called.
131
132
For instance::
133
134
class TemporaryDirectoryResource(TestResourceManager):
135
136
def clean(self, resource):
137
osutils.rmtree(resource)
138
139
def make(self):
140
return tempfile.mkdtemp()
141
142
def isDirty(self, resource):
143
# Can't detect when the directory is written to, so assume it
144
# can never be reused. We could list the directory, but that might
145
# not catch it being open as a cwd etc.
146
return True
147
148
The ``resources`` list on the TestResourceManager object is used to declare
149
dependencies. For instance, a DataBaseResource that needs a TemporaryDirectory
150
might be declared with a resources list::
151
152
class DataBaseResource(TestResourceManager):
153
154
resources = [("scratchdir", TemporaryDirectoryResource())]
155
156
Most importantly, two getResources to the same TestResourceManager with no
157
finishedWith call in the middle, will return the same object as long as it is
158
not dirty.
159
160
When a Test has a dependency and that dependency successfully completes but
161
returns None, the framework does *not* consider this an error: be sure to always
162
return a valid resource, or raise an error. Error handling hasn't been heavily
163
exercised, but any bugs in this area will be promptly dealt with.
164
165
A sample TestResourceManager can be found in the doc/ folder.
166
167
See pydoc testresources.TestResourceManager for details.
168
169
testresources.GenericResource
170
-----------------------------
171
172
Glue to adapt testresources to an existing resource-like class.
173
174
testresources.OptimisingTestSuite
175
---------------------------------
176
177
This TestSuite will introspect all the test cases it holds directly and if
178
they declare needed resources, will run the tests in an order that attempts to
179
minimise the number of setup and tear downs required. It attempts to achieve
180
this by callling getResource() and finishedWith() around the sequence of tests
181
that use a specific resource.
182
183
Tests are added to an OptimisingTestSuite as normal. Any standard library
184
TestSuite objects will be flattened, while any custom TestSuite subclasses
185
will be distributed across their member tests. This means that any custom
186
logic in test suites should be preserved, at the price of some level of
187
optimisation.
188
189
Because the test suite does the optimisation, you can control the amount of
190
optimising that takes place by adding more or fewer tests to a single
191
OptimisingTestSuite. You could add everything to a single OptimisingTestSuite,
192
getting global optimisation or you could use several smaller
193
OptimisingTestSuites.
194
195
196
testresources.TestLoader
197
------------------------
198
199
This is a trivial TestLoader that creates OptimisingTestSuites by default.
200
201
unittest.TestResult
202
-------------------
203
204
testresources will log activity about resource creation and destruction to the
205
result object tests are run with. 4 extension methods are looked for:
206
``startCleanResource``, ``stopCleanResource``, ``startMakeResource``,
207
``stopMakeResource``. ``testresources.tests.ResultWithResourceExtensions`` is
208
an example of a ``TestResult`` with these methods present.
209
210
Controlling Resource Reuse
211
==========================
212
213
When or how do I mark the resource dirtied?
214
215
The simplest approach is to have ``TestResourceManager.make`` call ``self.dirtied``:
216
the resource is always immediately dirty and will never be reused without first
217
being reset. This is appropriate when the underlying resource is cheap to
218
reset or recreate, or when it's hard to detect whether it's been dirtied or to
219
trap operations that change it.
220
221
Alternatively, override ``TestResourceManager.isDirty`` and inspect the resource to
222
see if it is safe to reuse.
223
224
Finally, you can arrange for the returned resource to always call back to
225
``TestResourceManager.dirtied`` on the first operation that mutates it.
226
227
FAQ
228
===
229
230
* Can I dynamically request resources inside a test method?
231
232
Generally, no, you shouldn't do this. The idea is that the resources are
233
declared statically, so that testresources can "smooth" resource usage across
234
several tests.
235
236
* If the resource is held inside the TestResourceManager object, and the
237
TestResourceManager is typically constructed inline in the test case
238
``resources`` attribute, how can they be shared across different test
239
classes?
240
241
Good question.
242
243
I guess you should arrange for a single instance to be held in an appropriate
244
module scope, then referenced by the test classes that want to share it.
245
10
246
Platform: UNKNOWN
247
Classifier: Development Status :: 6 - Mature
248
Classifier: Intended Audience :: Developers
249
Classifier: License :: OSI Approved :: BSD License
250
Classifier: License :: OSI Approved :: Apache Software License
251
Classifier: Operating System :: OS Independent
252
Classifier: Programming Language :: Python
253
Classifier: Topic :: Software Development :: Quality Assurance
254
Classifier: Topic :: Software Development :: Testing
Loggerhead is a web-based interface for Breezy
Version: 2.0.1