Repository files navigation

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 theFixtures contract inunittest compatible 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>

  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, you will need a testenvironment that supportsTestCase.addCleanup. Writing your own glue codeis easy. Alternatively, you can simply use Fixtures directly without anysupport code.

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

Standard Pythonunittest 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 tool,doesn'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 aTestCase 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 attributepath.

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

Minimally, subclassFixture, define_setUp to initialize your state,schedule a cleanup for whencleanUp is called, and you're done:

>>>importunittest>>>importfixtures>>>classNoddyFixture(fixtures.Fixture):...def_setUp(self):...self.frobnozzle=42...self.addCleanup(delattr,self,'frobnozzle')

This will initializefrobnozzle whensetUp is called, and whencleanUp is called get rid of thefrobnozzle attribute. Prior to version1.3.0fixtures recommended overridingsetUp. This is still supported, butsince it is harder to write leak-free fixtures in this fashion, it is notrecommended.

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:

>>>fromtesttools.contentimporttext_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 infn_result:

>>>importos.path>>>importshutil>>>importtempfile>>>defsetup_function():...returntempfile.mkdtemp()>>>defteardown_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 isMethodFixture which is useful for adapting alternatefixture implementations to Fixture:

>>>classMyServer:...defstart(self):...pass...defstop(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()])>>>withnoddy_with_logasx:...print (x.fixtures[0].frobnozzle)42

The example above introduces some of theFixture API. In order to be ableto clean 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 baseFixture also defines areset which 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 thesetUp andcleanUp methods. More convenient though is to use the included glue fromfixtures.TestWithFixtures which provides a mixin defininguseFixture(camel case becauseunittest is camel case throughout) method. It will callsetUp on the fixture, callself.addCleanup(fixture) to schedule acleanup, and return the fixture. This lets one write:

>>>importtesttools>>>importunittest

Note that we usetesttools.TestCase.testtools has it's ownimplementation ofuseFixture 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:

>>>withfixtures.FunctionFixture(setup_function,teardown_function)asfixture:...print (os.path.isdir(fixture.fn_result))True

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

>>>importsys>>>fromfixtures.fixtureimportMultipleExceptions>>>classBrokenFixture(fixtures.Fixture):...def_setUp(self):...self.addCleanup(lambda:1/0)...self.addCleanup(lambda:1/0)>>>fixture=BrokenFixture()>>>fixture.setUp()>>>try:...fixture.cleanUp()...exceptMultipleExceptions:...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:

>>>withWithLog()asl:...print(l.getDetails()['message'].as_text())foobarbaz

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 likeKeyboardInterrupt being caught inappropriately inthe calling layer, the original exception will be raised as-is and nodiagnostic data 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:

>>>classWithDep(fixtures.Fixture):...def__init__(self,tempdir,dependency_fixture):...super(WithDep,self).__init__()...self.tempdir=tempdir...self.dependency_fixture=dependency_fixture...defsetUp(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 thewebserver's 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 theFixture,FunctionFixture andMethodFixtureclasses, fixtures includes a number of pre-canned fixtures. The API docs forfixtures will list the complete set of these, should the docs be out of date ornot to hand. For the complete feature set of each fixture please see the APIdocs.

Trivial adapter to make aBytesIO (though it may in future auto-spill todisk for large content) and expose that as a detail object, for automaticinclusion in test failure descriptions. Very useful in combination withMonkeyPatch:

>>>fixture=fixtures.StringStream('my-content')>>>fixture.setUp()>>>withfixtures.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:

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

Replace or extend a logger's handlers. The behavior of this fixture depends onthe value of thenuke_handlers parameter: iftrue, the logger'sexisting handlers are removed and replaced by the provided handler, while iffalse the logger's set of handlers is extended by the provided handler:

>>>fromloggingimportStreamHandler>>>fixture=fixtures.LogHandler(StreamHandler())

Adaptsmock.patch.object to be used as a fixture:

>>>classFred:...value=1>>>fixture=fixtures.MockPatchObject(Fred,'value',2)>>>withfixture:...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 afixture:

>>>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 thetempfile module places temporaryfiles and directories in. This can be useful for containing the noise createdby code 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 thepackage.__path__ list. If the directory is already in the path,nothing happens, if it isn't then it is added onsetUp and removed oncleanUp:

>>>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 tosys.path. If the directory is already in thepath, nothing happens, if it isn't then it is added onsetUp and removed oncleanUp:

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

Trivial adapter to expose a file-like object as a detail object, for automaticinclusion in test failure descriptions.StringStream andBytesStreamprovided concrete users of this fixture.

This requires thefixtures[streams] extra.

Trivial adapter to make aStringIO (though it may in future auto-spill todisk for large content) and expose that as a detail object, for automaticinclusion in test failure descriptions. Very useful in combination withMonkeyPatch:

>>>fixture=fixtures.StringStream('stdout')>>>fixture.setUp()>>>withfixtures.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 aftertearDown.

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

There are two possibilities, controlled by thegentle 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.

Capture warnings for later analysis:

>>>fixture=fixtures.WarningsCapture()

The captured warnings are stored in thecaptures attribute of the fixtureaftersetUp.

Configure warnings filters during test runs:

>>>fixture=fixtures.WarningsFilter(...     [...         {...'action':'ignore',...'message':'foo',...'category':DeprecationWarning,...         },...     ]... )

Order is important: entries closer to the front of the list override entrieslater in the list, if both match a particular warning.

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

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.