[svn r63530] committing some old text about state management

--HG--
branch : trunk

py/doc/test-statemanage.txt

@@ -0,0 +1,61 @@
+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.