Repository files navigation

Copyright (c) 2010, Robert Collins <robertc@robertcollins.net>

Licensed under either the Apache License, Version 2.0 or the BSD 3-clauselicense at the users choice. A copy of both licenses are available in theproject source as Apache-2.0 and BSD. You may not use this file except incompliance with one of these two licences.

Unless required by applicable law or agreed to in writing, softwaredistributed under these licenses is distributed on an "AS IS" BASIS, WITHOUTWARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See thelicense you chose for the specific language governing permissions andlimitations under that license.

Fixtures defines a Python contract for reusable state / support logic,primarily for unit testing. Helper and adaption logic is included to make iteasy to write your own fixtures using the fixtures contract. Glue code isprovided that makes using fixtures that meet the Fixtures contract in unittestcompatible test cases easy and straight forward.

• Python 3.7+This is the base language fixtures is written in and for.
• pbrUsed for version and release management of fixtures.

Thefixtures[streams] extra adds:

• testtools <https://launchpad.net/testtools> 0.9.22 or newer.testtools provides helpful glue functions for the details API used to reportinformation about a fixture (whether its used in a testing or productionenvironment).

For use in a unit test suite using the included glue, one of:

• bzrlib.tests
• Or any other test environment that supports TestCase.addCleanup.

Writing your own glue code is easy, or you can simply use Fixtures directlywithout any support code.

To run the test suite for fixtures, testtools is needed.

Standard Python unittest.py provides no obvious method for making and reusingstate needed in a test case other than by adding a method on the test class.This scales poorly - complex helper functions propagating up a test classhierarchy is a regular pattern when this is done. Mocking while a great tooldoesn't itself prevent this (and helpers to mock complex things can accumulatein the same way if placed on the test class).

By defining a uniform contract where helpers have no dependency on the testclass we permit all the regular code hygiene activities to take place withoutthe distorting influence of being in a class hierarchy that is modelling anentirely different thing - which is what helpers on a TestCase suffer from.

A Fixture represents some state. Each fixture has attributes on it that arespecific to the fixture. For instance, a fixture representing a directory thatcan be used for temporary files might have a attribute 'path'.

Most fixtures have completepydoc documentation, so be sure to checkpydoc fixtures for usage information.

Minimally, subclass Fixture, define _setUp to initialize your state and schedulea cleanup for when cleanUp is called and you're done:

>>> import unittest>>> import fixtures>>> class NoddyFixture(fixtures.Fixture):...     def _setUp(self):...         self.frobnozzle = 42...         self.addCleanup(delattr, self, 'frobnozzle')

This will initialize frobnozzle whensetUp is called, and whencleanUpis called get rid of the frobnozzle attribute. Prior to version 1.3.0 fixturesrecommended overridingsetUp. This is still supported, but since it isharder to write leak-free fixtures in this fashion, it is not recommended.

If your fixture has diagnostic data - for instance the log file of anapplication server, or log messages, it can expose that by creating a contentobject (testtools.content.Content) and callingaddDetail.

>>>from testtools.contentimport text_content>>>classWithLog(fixtures.Fixture):...def_setUp(self):...self.addDetail('message', text_content('foo bar baz'))

The methoduseFixture will use another fixture, callsetUp on it, callself.addCleanup(thefixture.cleanUp), attach any details from it and returnthe fixture. This allows simple composition of different fixtures.

>>>classReusingFixture(fixtures.Fixture):...def_setUp(self):...self.noddy=self.useFixture(NoddyFixture())

There is a helper for adapting a function or function pair into Fixtures. itputs the result of the function in fn_result:

>>> import os.path>>> import shutil>>> import tempfile>>> def setup_function():...     return tempfile.mkdtemp()>>> def teardown_function(fixture):...     shutil.rmtree(fixture)>>> fixture = fixtures.FunctionFixture(setup_function, teardown_function)>>> fixture.setUp()>>> print (os.path.isdir(fixture.fn_result))True>>> fixture.cleanUp()

This can be expressed even more pithily:

>>> fixture= fixtures.FunctionFixture(tempfile.mkdtemp, shutil.rmtree)>>> fixture.setUp()>>>print (os.path.isdir(fixture.fn_result))True>>> fixture.cleanUp()

Another variation is MethodFixture which is useful for adapting alternatefixture implementations to Fixture:

>>> class MyServer:...    def start(self):...        pass...    def stop(self):...        pass>>> server = MyServer()>>> fixture = fixtures.MethodFixture(server, server.start, server.stop)

You can also combine existing fixtures usingCompoundFixture:

>>> noddy_with_log = fixtures.CompoundFixture([NoddyFixture(),...                                            WithLog()])>>> with noddy_with_log as x:...     print (x.fixtures[0].frobnozzle)42

The example above introduces some of the Fixture API. In order to be able toclean up after a fixture has been used, all fixtures define acleanUpmethod which should be called when a fixture is finished with.

Because it's nice to be able to build a particular set of related fixtures inadvance of using them, fixtures also have asetUp method which should becalled before trying to use them.

One common desire with fixtures that are expensive to create is to reuse themin many test cases; to support this the base Fixture also defines aresetwhich callsself.cleanUp(); self.setUp(). Fixtures that can moreefficiently make themselves reusable should override this method. This can thenbe used with multiple test state via things liketestresources,setUpClass, orsetUpModule.

When using a fixture with a test you can manually call the setUp and cleanUpmethods. More convenient though is to use the included glue fromfixtures.TestWithFixtures which provides a mixin defininguseFixture (camel case because unittest is camel case throughout) method.It will call setUp on the fixture, call self.addCleanup(fixture) to schedule acleanup, and return the fixture. This lets one write:

>>> import testtools>>> import unittest

Note that we usetesttools.TestCase. testtools has it's own implementationofuseFixture so there is no need to usefixtures.TestWithFixtures withtesttools.TestCase.

>>>classNoddyTest(testtools.TestCase,fixtures.TestWithFixtures):...deftest_example(self):...         fixture=self.useFixture(NoddyFixture())...self.assertEqual(42, fixture.frobnozzle)>>> result= unittest.TestResult()>>> _= NoddyTest('test_example').run(result)>>>print (result.wasSuccessful())True

Fixtures implement the context protocol, so you can also use a fixture as acontext manager:

>>> with fixtures.FunctionFixture(setup_function, teardown_function) as fixture:...    print (os.path.isdir(fixture.fn_result))True

When multiple cleanups error, fixture.cleanUp() will raise a wrapper exceptionrather than choosing an arbitrary single exception to raise:

>>> import sys>>> from fixtures.fixture import MultipleExceptions>>> class BrokenFixture(fixtures.Fixture):...     def _setUp(self):...         self.addCleanup(lambda:1/0)...         self.addCleanup(lambda:1/0)>>> fixture = BrokenFixture()>>> fixture.setUp()>>> try:...    fixture.cleanUp()... except MultipleExceptions:...    exc_info = sys.exc_info()>>> print (exc_info[1].args[0][0].__name__)ZeroDivisionError

Fixtures often expose diagnostic details that can be useful for tracking downissues. ThegetDetails method will return a dict of all the attacheddetails, but can only be called beforecleanUp is called. Each detailobject is an instance oftesttools.content.Content.

>>>with WithLog()as l:...print(l.getDetails()['message'].as_text())foo bar baz

The examples above used_setUp rather thansetUp because the baseclass implementation ofsetUp acts to reduce the chance of leakingexternal resources if an error is raised from_setUp. Specifically,setUp contains a try:/except: block which catches all exceptions, capturesany registered detail objects, and callsself.cleanUp before propagatingthe error. As long as you take care to register any cleanups before callingthe code that may fail, this will cause them to be cleaned up. The captureddetail objects are provided to the args of the raised exception.

If the error that occurred was a subclass ofException thensetUp willraiseMultipleExceptions with the last element being aSetupError thatcontains the detail objects. Otherwise, to prevent causing normallyuncatchable errors like KeyboardInterrupt being caught inappropriately in thecalling layer, the original exception will be raised as-is and no diagnosticdata other than that from the original exception will be available.

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

Consider the case of testing using aTempDir with two fixtures built on topof it; say a small database and a web server. Writing either one is nearlytrivial. However handlingreset() correctly is hard: both the database andweb server would reasonably expect to be able to discard operating systemresources they may have open within the temporary directory before its removed.A recursivereset() implementation would work for one, but not both.Callingreset() on theTempDir instance between each test is probablydesirable but we don't want to have to do a completecleanUp of the higherlayer fixtures (which would make theTempDir be unused and triviallyresettable. We have a few options available to us.

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

A simple option is to just provide an explicit dependency fixture for thehigher layer fixtures to use. This pushes complexity out of the core and ontousers 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 dependencybeing reset underneath them. This is insufficient if the fixtures wouldblock the dependency resetting (for instance by holding file locks openin a tempdir - on Windows this will prevent the directory being deleted).

Another approach whichfixtures neither helps nor hinders is to raisea signal of some sort for each user of a fixture before it is reset. In theexample here,TempDir might offer a subscribers attribute that both theDB and web server would be registered in. Callingreset orcleanUpon the tempdir would trigger a callback to all the subscribers; the DB andweb server reset methods would look something like:

>>>defreset(self):...ifnotself._cleaned:...self._clean()

(Their action on the callback from the tempdir would be to do whatever workwas needed and setself._cleaned.) This approach has the (perhaps)surprising effect that resetting the webserver may reset the DB - if thewebserver were to be depending ontempdir.reset as a way to reset thewebservers state.

Another approach which is not currently implemented is to provide an objectgraph of dependencies and a reset mechanism that can traverse that, along witha separation between 'reset starting' and 'reset finishing' - the DB andwebserver would both have theirreset_starting methods called, then thetempdir would be reset, and finally the DB and webserver would havereset_finishing called.

In addition to the Fixture, FunctionFixture and MethodFixture classes fixturesincludes a number of precanned fixtures. The API docs for fixtures will listthe complete set of these, should the dcs be out of date or not to hand. Forthe complete feature set of each fixture please see the API docs.

Trivial adapter to make a BytesIO (though it may in future auto-spill to diskfor large content) and expose that as a detail object, for automatic inclusionin 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()

This requires thefixtures[streams] extra.

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

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

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

>>> fixture= fixtures.FakeLogger()

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

>>>from ioimport BytesIO>>> fixture= fixtures.FakePopen(lambda_:{'stdout': BytesIO('foobar')})

Adaptsmock.patch.object to be used as a Fixture.

>>>classFred:...     value=1>>> fixture= fixtures.MockPatchObject(Fred,'value',2)>>>with fixture:...     Fred().value2>>> Fred().value1

Adaptsmock.patch to be used as a Fixture.

>>> fixture= fixtures.MockPatch('subprocess.Popen.returncode',3)

Adaptsmock.patch.multiple to be used as a Fixture.

>>> fixture= fixtures.MockPatchMultiple('subprocess.Popen',returncode=3)

Control the value of a named Python attribute.

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

Note that there are some complexities when patching methods - please see theAPI documentation for details.

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

>>> fixture= fixtures.NestedTempfile()

Adds a single directory to the path for an existing Python package. This addsto the package.__path__ list. If the directory is already in the path, nothinghappens, if it isn't then it is added on setUp and removed on cleanUp.

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

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

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

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')

Trivial adapter to make a StringIO (though it may in future auto-spill to diskfor large content) and expose that as a detail object, for automatic inclusionin 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()

This requires thefixtures[streams] extra.

Create a temporary directory and clean it up later.

>>> fixture= fixtures.TempDir()

The created directory is stored in thepath attribute of the fixture aftersetUp.

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

>>> fixture= fixtures.TempHomeDir()

The created directory is stored in thepath attribute of the fixture aftersetUp.

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

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

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 asingle process. Using more than one has undefined results. (This could beimproved by chaining alarms.)

Note: Currently supported only on Unix because it relies on thealarmsystem call.

Fixtures has its project homepage on GitHub<https://github.com/testing-cabal/fixtures>.