← Back to branch summary

~ubuntu-branches/ubuntu/saucy/python-fixtures/saucy-proposed

« back to all changes in this revision

Viewing changes to README

  • Committer: Bazaar Package Importer
  • Author(s): Robert Collins
  • Date: 2011-06-23 20:40:06 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20110623204006-meclc7muiy92tv0b
* New upstream release.
* Runtime dependency on testtools due to upstream change.

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
26
26
============
27
27
 
28
28
* Python 2.4+
 
29
  This is the base language fixtures is written in and for.
 
30
 
 
31
* testtools <https://launchpad.net/testtools> 0.9.8 or newer.
 
32
  testtools provides helpful glue functions for the details API used to report
 
33
  information about a fixture (whether its used in a testing or production
 
34
  environment).
29
35
 
30
36
For use in a unit test suite using the included glue, one of:
31
37
 
35
41
 
36
42
* bzrlib.tests
37
43
 
38
 
* testtools <https://launchpad.net/testtools>
39
 
 
40
44
* Or any other test environment that supports TestCase.addCleanup.
41
45
 
42
46
Writing your own glue code is easy, or you can simply use Fixtures directly
184
188
  >>> print exc_info[1].args[0][0]
185
189
  <type 'exceptions.ZeroDivisionError'>
186
190
 
 
191
Shared Dependencies
 
192
+++++++++++++++++++
 
193
 
 
194
A common use case within complex environments is having some fixtures shared by
 
195
other ones.
 
196
 
 
197
Consider the case of testing using a ``TempDir`` with two fixtures built on top
 
198
of it; say a small database and a web server. Writing either one is nearly
 
199
trivial. However handling ``reset()`` correctly is hard: both the database and
 
200
web server would reasonably expect to be able to discard operating system
 
201
resources they may have open within the temporary directory before its removed.
 
202
A recursive ``reset()`` implementation would work for one, but not both.
 
203
Calling ``reset()`` on the ``TempDir`` instance between each test is probably
 
204
desirable but we don't want to have to do a complete ``cleanUp`` of the higher
 
205
layer fixtures (which would make the ``TempDir`` be unused and trivially
 
206
resettable. We have a few options available to us.
 
207
 
 
208
Imagine that the webserver does not depend on the DB fixture in any way - we
 
209
just want the webserver and DB fixture to coexist in the same tempdir.
 
210
 
 
211
A simple option is to just provide an explicit dependency fixture for the
 
212
higher layer fixtures to use.  This pushes complexity out of the core and onto
 
213
users of fixtures::
 
214
 
 
215
  >>> class WithDep(fixtures.Fixture):
 
216
  ...     def __init__(self, tempdir, dependency_fixture):
 
217
  ...         super(WithDep, self).__init__()
 
218
  ...         self.tempdir = tempdir
 
219
  ...         self.dependency_fixture = dependency_fixture
 
220
  ...     def setUp(self):
 
221
  ...         super(WithDep, self).setUp()
 
222
  ...         self.addCleanup(self.dependency_fixture.cleanUp)
 
223
  ...         self.dependency_fixture.setUp()
 
224
  ...         # we assume that at this point self.tempdir is usable.
 
225
  >>> DB = WithDep
 
226
  >>> WebServer = WithDep
 
227
  >>> tempdir = fixtures.TempDir()
 
228
  >>> db = DB(tempdir, tempdir)
 
229
  >>> server = WebServer(tempdir, db)
 
230
  >>> server.setUp()
 
231
  >>> server.cleanUp()
 
232
 
 
233
Another option is to write the fixtures to gracefully handle a dependency
 
234
being reset underneath them. This is insufficient if the fixtures would
 
235
block the dependency resetting (for instance by holding file locks open
 
236
in a tempdir - on Windows this will prevent the directory being deleted).
 
237
 
 
238
Another approach which ``fixtures`` neither helps nor hinders is to raise
 
239
a signal of some sort for each user of a fixture before it is reset. In the
 
240
example here, ``TempDir`` might offer a subscribers attribute that both the
 
241
DB and web server would be registered in. Calling ``reset`` or ``cleanUp``
 
242
on the tempdir would trigger a callback to all the subscribers; the DB and
 
243
web server reset methods would look something like:
 
244
 
 
245
  >>> def reset(self):
 
246
  ...     if not self._cleaned:
 
247
  ...         self._clean()
 
248
 
 
249
(Their action on the callback from the tempdir would be to do whatever work
 
250
was needed and set ``self._cleaned``.) This approach has the (perhaps)
 
251
suprising effect that resetting the webserver may reset the DB - if the
 
252
webserver were to be depending on ``tempdir.reset`` as a way to reset the
 
253
webservers state.
 
254
 
 
255
Another approach which is not currently implemented is to provide an object
 
256
graph of dependencies and a reset mechanism that can traverse that, along with
 
257
a separation between 'reset starting' and 'reset finishing' - the DB and
 
258
webserver would both have their ``reset_starting`` methods called, then the
 
259
tempdir would be reset, and finally the DB and webserver would have
 
260
``reset_finishing`` called.
 
261
 
187
262
Stock Fixtures
188
263
==============
189
264
 
208
283
  ...     pass
209
284
  >>> fixture = fixtures.MonkeyPatch('__builtin__.open', fake_open)
210
285
 
 
286
PackagePathEntry
 
287
++++++++++++++++
 
288
 
 
289
Adds a single directory to the path for an existing python package. This adds
 
290
to the package.__path__ list. If the directory is already in the path, nothing
 
291
happens, if it isn't then it is added on setUp and removed on cleanUp.
 
292
 
 
293
  >>> fixture = fixtures.PackagePathEntry('package/name', '/foo/bar')
 
294
 
211
295
PopenFixture
212
296
++++++++++++
213
297
 
226
310
 
227
311
  >>> fixture = fixtures.PythonPackage('foo.bar', [('quux.py', '')])
228
312
 
 
313
PythonPathEntry
 
314
+++++++++++++++
 
315
 
 
316
Adds a single directory to sys.path. If the directory is already in the path,
 
317
nothing happens, if it isn't then it is added on setUp and removed on cleanUp.
 
318
 
 
319
  >>> fixture = fixtures.PythonPathEntry('/foo/bar')
 
320
 
229
321
TempDir
230
322
+++++++
231
323
 
232
324
Create a temporary directory and clean it up later.
233
325
 
234
326
  >>> fixture = fixtures.TempDir()
 
327
 
 
328
The created directory is stored in the ``path`` attribute of the fixture after
 
329
setUp.