Metadata-Version: 1.0
Name: fixtures
Version: 0.2
Summary: Fixtures, reusable state for writing clean tests and more.
Home-page: https://launchpad.net/python-fixtures
Author: Robert Collins
Author-email: robertc@robertcollins.net
License: UNKNOWN
Description: *************************************************************
        fixtures: Fixtures with cleanups for testing and convenience.
        *************************************************************
        
          Copyright (c) 2010, Robert Collins <robertc@robertcollins.net>
          
          Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
          license at the users choice. A copy of both licenses are available in the
          project source as Apache-2.0 and BSD. You may not use this file except in
          compliance with one of these two licences.
          
          Unless required by applicable law or agreed to in writing, software
          distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
          WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
          license you chose for the specific language governing permissions and
          limitations 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 it
        easy to write your own fixtures using the fixtures contract. Glue code is
        provided that makes using fixtures that meet the Fixtures contract in unittest
        compatible test cases easy and straight forward.
        
        Dependencies
        ============
        
        * Python 2.4+
        
        For use in a unit test suite using the included glue, one of:
        * Python 2.7
        * unittest2
        * bzrlib.tests
        * testtools <https://launchpad.net/testtools>
        * Or any other test environment that supports TestCase.addCleanup.
        
        Writing your own glue code is easy, or you can simply use Fixtures directly
        without any support code.
        
        To run the test suite for fixtures, testtools is needed.
        
        Why Fixtures
        ============
        
        Standard Python unittest.py provides no obvious method for making and reusing
        state needed in a test case other than by adding a method on the test class.
        This scales poorly - complex helper functions propogating up a test class
        hierarchy 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 accumulate
        in the same way if placed on the test class).
        
        By defining a uniform contract where helpers have no dependency on the test
        class we permit all the regular code hygiene activities to take place without
        the distorting influence of being in a class hierarchy that is modelling an
        entirely different thing - which is what helpers on a TestCase suffer from.
        
        About Fixtures
        ==============
        
        A Fixture represents some state. Each fixture has attributes on it that are
        specific to the fixture. For instance, a fixture representing a directory that
        can be used for temporary files might have a attribute 'path'.
        
        Creating Fixtures
        =================
        
        Minimally, subclass Fixture, define setUp to initialize your state and schedule
        a cleanup for when cleanUp is called and you're done::
        
          >>> import unittest
          >>> import fixtures
          >>> class NoddyFixture(fixtures.Fixture):
          ...     def setUp(self):
          ...         super(NoddyFixture, self).setUp()
          ...         self.frobnozzle = 42
          ...         self.addCleanup(delattr, self, 'frobnozzle')
        
        This will initialize frobnozzle when setUp is called, and when cleanUp is
        called get rid of the frobnozzle attribute.
        
        There is a helper for adapting a function or function pair into Fixtures. it
        puts 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()
          []
        
        The Fixture API
        ===============
        
        The example above introduces some of the Fixture API. In order to be able to
        clean up after a fixture has been used, all fixtures define a ``cleanUp``
        method which should be called when a fixture is finished with.
        
        Because its nice to be able to build a particular set of related fixtures in
        advance of using them, fixtures also have define a ``setUp`` method which
        should be called before trying to use them.
        
        One common desire with fixtures that are expensive to create is to reuse them
        in many test cases; to support this the base Fixture also defines a ``reset``
        which calls ``self.cleanUp(); self.setUp()``. Fixtures that can more
        efficiently make themselves reusable should override this method. This can then
        be used with multiple test state via things like ``testresources``,
        ``setUpClass``, or ``setUpModule``.
        
        When using a fixture with a test you can manually call the setUp and cleanUp
        methods. More convenient though is to use the included glue from
        ``fixtures.TestWithFixtures`` which provides a mixin defining
        ``useFixture`` (camel case because unittest is camel case throughout) method.
        It will call setUp on the fixture, call self.addCleanup(fixture) to schedule a
        cleanup, and return the fixture. This lets one write::
        
          >>> import testtools
          >>> import unittest
        
        Note that we use testtools TestCase here as we need to guarantee a
        TestCase.addCleanup method.
        
          >>> class NoddyTest(testtools.TestCase, fixtures.TestWithFixtures):
          ...     def test_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 a
        context manager::
        
          >>> with fixtures.FunctionFixture(setup_function, teardown_function) as fixture:
          ...    print os.path.isdir(fixture.fn_result)
          True
        
        Note that the context protocol does not report on all exceptions raised within
        it - only the ultimate exception is raised. In tests though, it is desirable to
        know all the exceptions that occur (even though some may be cascading) so that
        tests in slow environments can have as much analysis and correction done on them
        as possible. Fixtures support this by returning a list of the exc_info
        information for all exceptions occuring in the cleanUp() call. The context
        manager support as such is a down-grading of the raw capabilities of fixtures -
        but it can be very useful when the loss of fidelity is aacceptable.
        Specificaly, when multiple exceptions are raised from the cleanups in fixtures,
        the first one will be raised from the __exit__ of the outermost fixture.
        
        To demonstrate the basic behaviour of content managers:
        
          >>> from contextlib import contextmanager
          >>> actions = []
          >>> @contextmanager
          ... def raiser(message):
          ...    try:
          ...        yield
          ...    finally:
          ...        actions.append(message)
          ...        raise RuntimeError(message)
          >>> with raiser("outer"):
          ...     with raiser("inner"):
          ...         pass
          Traceback (most recent call last):
            File "demo.py", line 11, in <module>
              print "test code"
            File "/usr/lib/python2.6/contextlib.py", line 23, in __exit__
              self.gen.next()
            File "demo.py", line 7, in raiser
              raise RuntimeError(message)
          RuntimeError: outer
          >>> actions
          ['inner', 'outer']
        
        
        With a fixture that has two cleanups, which both raise, both exceptions will be
        available in the return value of cleanUp.
        
Platform: UNKNOWN
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
