section on xUnit style setups, better linking, some streamlining

--HG--
branch : trunk

doc/test/features.txt

@@ -36,8 +36,20 @@ or class with a leading ``Test`` name is collected.
 Rapidly write integration, functional, unit tests 
 ===================================================
 
-py.test provides 
+XXX 
 
+Unique test state setup/fixture methods 
+===================================================
+
+py.test provides the `unique funcargs mechanism`_ 
+for constructing test fixtures and handling 
+complex test scenarios.  You can also 
+use `traditional xUnit style setup`_ for
+existing code bases or if you prefer 
+it for your unit tests. 
+
+.. _`unique funcargs mechanism`: funcargs.html
+.. _`traditional xUnit style setup`: xunit_setup.html
 
 load-balance tests to multiple CPUs
 ===================================

doc/test/funcargs.txt

@@ -153,7 +153,7 @@ into ``myapp.py``:
         def question(self):
             return 6 * 9
 
-.. _`local plugin`: test-ext.html#local-plugin
+.. _`local plugin`: ext.html#local-plugin
 
 Example: specifying funcargs in test modules or classes
 ---------------------------------------------------------
@@ -294,7 +294,7 @@ function argument is provided.
 Note that we make use here of `py.path.local`_ objects
 that provide uniform access to the local filesystem. 
 
-.. _`py.path.local`: path.html#local
+.. _`py.path.local`: ../path.html#local
 
 Questions and Answers
 ==================================

doc/test/statemanage.txt

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

doc/test/xunit_setup.txt

@@ -0,0 +1,73 @@
+====================================
+xUnit style setup
+====================================
+
+.. _`funcargs`: funcargs.html
+.. _`xUnit`: http://en.wikipedia.org/wiki/XUnit
+
+** Note that since version 1.0 py.test offers `funcargs`_ 
+for simple and complex test setup needs.  Especially 
+if you want to do functional and integration testing,
+but also fo runittesting, it is highly recommended 
+that you consider using `funcargs`_ for keeping 
+a clean and maintenable test suite. **
+
+Python, Java and 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. 
+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
+