test_ok1/doc/test/xunit_setup.txt

====================================
extended xUnit style setup
====================================

.. _`funcargs`: funcargs.html
.. _`test parametrization`: funcargs.html#parametrizing-tests
.. _`unittest plugin`: plugin/unittest.html
.. _`xUnit`: http://en.wikipedia.org/wiki/XUnit

Note: 

    Since version 1.0 funcargs_ present the new and 
    more powerful way to manage test setups with larger
    test suites.  *funcargs* also provide flexible 
    `test parametrization`_ which goes way beyond
    what you can do with the xUnit setup/teardown-method 
    patter. 

Python, Java and many other languages have a tradition
of using xUnit_ style testing. This typically 
involves the call of a ``setup`` method before
a test function is run and ``teardown`` after
it finishes.  With ``py.test`` there are three 
scopes for which you can provide setup/teardown
hooks to provide test fixtures: per-module, per-class 
and per-method/function. ``py.test`` will 
discover and call according methods automatically. 

The `unittest plugin`_  also will intregate ``unittest.TestCase`` 
instances into a test run and call respective setup/teardown methods.

All setup/teardown methods are optional.  

The following methods are called at module level if they exist:

.. sourcecode:: python

    def setup_module(module):
        """ setup up any state specific to the execution
            of the given module. 
        """

    def teardown_module(module):
        """ teardown any state that was previously setup 
            with a setup_module method. 
        """

The following hooks are available for test classes:

.. sourcecode:: python

    def setup_class(cls): 
        """ setup up any state specific to the execution
            of the given class (which usually contains tests). 
        """

    def teardown_class(cls): 
        """ teardown any state that was previously setup 
            with a call to setup_class.
        """

    def setup_method(self, method):
        """ setup up any state tied to the execution of the given 
            method in a class.  setup_method is invoked for every 
            test method of a class. 
        """

    def teardown_method(self, method): 
        """ teardown any state that was previously setup 
            with a setup_method call. 
        """

The last two hooks, ``setup_method`` and ``teardown_method``, are
equivalent to ``setUp`` and ``tearDown`` in the Python standard
library's `unittest.py module`_.

Note that it possible that setup/teardown pairs are invoked multiple 
times per testing process. 

.. _`unittest.py module`: http://docs.python.org/library/unittest.html