=================
Managing state
=================

funcargs: provding arguments for test functions
===========================================================

XXX write docs 

Managing test state across test modules, classes and methods 
============================================================

Often you want to create some files, database connections or other
state in order to run tests in a certain environment.  With
``py.test`` there are three scopes for which you can provide hooks to
manage such state.  Again, ``py.test`` will detect these hooks in
modules on a name basis. The following module-level hooks will
automatically be called by the session::

    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::

    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 ``unitest`` module.

All setup/teardown methods are optional.  You could have a
``setup_module`` but no ``teardown_module`` and the other way round.

Note that while the test session guarantees that for every ``setup`` a
corresponding ``teardown`` will be invoked (if it exists) it does
*not* guarantee that any ``setup`` is called only happens once. For
example, the session might decide to call the ``setup_module`` /
``teardown_module`` pair more than once during the execution of a test
module.