fixtures 0.3.12

Shared Dependencies

A common use case within complex environments is having some fixtures shared by other ones.

Consider the case of testing using a TempDir with two fixtures built on top of it; say a small database and a web server. Writing either one is nearly trivial. However handling reset() correctly is hard: both the database and web server would reasonably expect to be able to discard operating system resources they may have open within the temporary directory before its removed. A recursive reset() implementation would work for one, but not both. Calling reset() on the TempDir instance between each test is probably desirable but we don’t want to have to do a complete cleanUp of the higher layer fixtures (which would make the TempDir be unused and trivially resettable. We have a few options available to us.

Imagine that the webserver does not depend on the DB fixture in any way - we just want the webserver and DB fixture to coexist in the same tempdir.

A simple option is to just provide an explicit dependency fixture for the higher layer fixtures to use. This pushes complexity out of the core and onto users of fixtures:

>>> class WithDep(fixtures.Fixture):
...     def __init__(self, tempdir, dependency_fixture):
...         super(WithDep, self).__init__()
...         self.tempdir = tempdir
...         self.dependency_fixture = dependency_fixture
...     def setUp(self):
...         super(WithDep, self).setUp()
...         self.addCleanup(self.dependency_fixture.cleanUp)
...         self.dependency_fixture.setUp()
...         # we assume that at this point self.tempdir is usable.
>>> DB = WithDep
>>> WebServer = WithDep
>>> tempdir = fixtures.TempDir()
>>> db = DB(tempdir, tempdir)
>>> server = WebServer(tempdir, db)
>>> server.setUp()
>>> server.cleanUp()

Another option is to write the fixtures to gracefully handle a dependency being reset underneath them. This is insufficient if the fixtures would block the dependency resetting (for instance by holding file locks open in a tempdir - on Windows this will prevent the directory being deleted).

Another approach which fixtures neither helps nor hinders is to raise a signal of some sort for each user of a fixture before it is reset. In the example here, TempDir might offer a subscribers attribute that both the DB and web server would be registered in. Calling reset or cleanUp on the tempdir would trigger a callback to all the subscribers; the DB and web server reset methods would look something like:

>>> def reset(self):
...     if not self._cleaned:
...         self._clean()

(Their action on the callback from the tempdir would be to do whatever work was needed and set self._cleaned.) This approach has the (perhaps) suprising effect that resetting the webserver may reset the DB - if the webserver were to be depending on tempdir.reset as a way to reset the webservers state.

Another approach which is not currently implemented is to provide an object graph of dependencies and a reset mechanism that can traverse that, along with a separation between ‘reset starting’ and ‘reset finishing’ - the DB and webserver would both have their reset_starting methods called, then the tempdir would be reset, and finally the DB and webserver would have reset_finishing called.

ByteStream

Trivial adapter to make a BytesIO (though it may in future auto-spill to disk for large content) and expose that as a detail object, for automatic inclusion in test failure descriptions. Very useful in combination with MonkeyPatch.

>>> fixture = fixtures.StringStream('my-content')
>>> fixture.setUp()
>>> with fixtures.MonkeyPatch('sys.something', fixture.stream):
...     pass
>>> fixture.cleanUp()

EnvironmentVariable

Isolate your code from environmental variables, delete them or set them to a new value.

>>> fixture = fixtures.EnvironmentVariable('HOME')

FakeLogger

Isolate your code from an external logging configuration - so that your test gets the output from logged messages, but they don’t go to e.g. the console.

>>> fixture = fixtures.FakeLogger()

FakePopen

Pretend to run an external command rather than needing it to be present to run tests.

>>> from testtools.compat import BytesIO
>>> fixture = fixtures.FakePopen(lambda _:{'stdout': BytesIO('foobar')})

MonkeyPatch

Control the value of a named python attribute.

>>> def fake_open(path, mode):
...     pass
>>> fixture = fixtures.MonkeyPatch('__builtin__.open', fake_open)

NestedTempfile

Change the default directory that the tempfile module places temporary files and directories in. This can be useful for containing the noise created by code which doesn’t clean up its temporary files. This does not affect temporary file creation where an explicit containing directory was provided.

>>> fixture = fixtures.NestedTempfile()

PackagePathEntry

Adds a single directory to the path for an existing python package. This adds to the package.__path__ list. If the directory is already in the path, nothing happens, if it isn’t then it is added on setUp and removed on cleanUp.

>>> fixture = fixtures.PackagePathEntry('package/name', '/foo/bar')

PythonPackage

Creates a python package directory. Particularly useful for testing code that dynamically loads packages/modules, or for mocking out the command line entry points to Python programs.

>>> fixture = fixtures.PythonPackage('foo.bar', [('quux.py', '')])

PythonPathEntry

Adds a single directory to sys.path. If the directory is already in the path, nothing happens, if it isn’t then it is added on setUp and removed on cleanUp.

>>> fixture = fixtures.PythonPathEntry('/foo/bar')

StringStream

Trivial adapter to make a StringIO (though it may in future auto-spill to disk for large content) and expose that as a detail object, for automatic inclusion in test failure descriptions. Very useful in combination with MonkeyPatch.

>>> fixture = fixtures.StringStream('stdout')
>>> fixture.setUp()
>>> with fixtures.MonkeyPatch('sys.stdout', fixture.stream):
...     pass
>>> fixture.cleanUp()

TempDir

Create a temporary directory and clean it up later.

>>> fixture = fixtures.TempDir()

The created directory is stored in the path attribute of the fixture after setUp.

TempHomeDir

Create a temporary directory and set it as $HOME in the environment.

>>> fixture = fixtures.TempHomeDir()

The created directory is stored in the path attribute of the fixture after setUp.

The environment will now have $HOME set to the same path, and the value will be returned to its previous value after tearDown.

Timeout

Aborts if the covered code takes more than a specified number of whole wall-clock seconds.

There are two possibilities, controlled by the ‘gentle’ argument: when gentle, an exception will be raised and the test (or other covered code) will fail. When not gentle, the entire process will be terminated, which is less clean, but more likely to break hangs where no Python code is running.

Caution: Only one timeout can be active at any time across all threads in a single process. Using more than one has undefined results. (This could be improved by chaining alarms.)

Note: Currently supported only on Unix because it relies on the alarm system call.