[py-svn] r6936 - in py/dist: doc example example/test

[hpk at codespeak.net]

Author: hpk
Date: Thu Oct 14 20:59:31 2004
New Revision: 6936

Added:
   py/dist/example/
   py/dist/example/test/
   py/dist/example/test/test_setup_flow_example.py
Modified:
   py/dist/doc/test.txt
Log:
- added example directory 

- added test-example for setup_flow 

- modified test.txt documentation to include 
  this new example, inspired by a suggestion 
  from Ian Bicking



Modified: py/dist/doc/test.txt
==============================================================================
--- py/dist/doc/test.txt	(original)
+++ py/dist/doc/test.txt	Thu Oct 14 20:59:31 2004
@@ -78,6 +78,14 @@
 tests. This output is only displayed when the test fails, 
 otherwise you will not see it.  
 
+order of execution is guaranteed
+--------------------------------
+
+Great care is taken that by default all tests run in the order 
+in which they appear in the files. If you run tests multiple times
+you will find that they execute in exactly the same order
+within each file. 
+
 Managing test state across test modules, classes and methods 
 ------------------------------------------------------------ 
 
@@ -118,15 +126,66 @@
 While the test driver guarantees that for every ``setup`` a
 corresponding ``teardown`` will be invoked (if it exists) it
 does *not* guarantee that it only happens once. For example,
-the driver might decide to call the
-setup_module/teardown_module pair more than once during the
-execution of a test module. 
-
-Note also that all setup/teardown  methods are optional.  For 
-example, you can have a setup_module but no teardown_module
-and the other way round. 
+the driver might decide to call the ``setup_module`` /
+``teardown_module`` pair more than once during the execution
+of a test module. 
+
+Note also that all setup/teardown  methods are optional.  You could
+have a ``setup_module`` but no ``teardown_module`` and the other way round. 
+
+Working Examples
+================
+
+Example for managing state at module, class and method level 
+------------------------------------------------------------
+
+Here is a working example for what goes on when you setup modules, 
+classes and methods:: 
+
+    # [[from example/test/test_setup_flow_example.py]]
+
+    def setup_module(module):
+        module.TestStateFullThing.classcount = 0
+
+    class TestStateFullThing:
+        def setup_class(cls):
+            cls.classcount += 1
+
+        def teardown_class(cls):
+            cls.classcount -= 1
+
+        def setup_method(self, method):
+            self.id = eval(method.func_name[5:])
+
+        def test_42(self):
+            assert self.classcount == 1
+            assert self.id == 42
+
+        def test_23(self):
+            assert self.classcount == 1
+            assert self.id == 23
+
+    def teardown_module(module):
+        assert module.TestStateFullThing.classcount == 0
 
+For this example the control flow happens as follows::
 
+    import test_setup_flow_example
+    setup_module(test_setup_flow_example)
+       setup_class(TestStateFullThing) 
+           instance = TestStateFullThing()
+           setup_method(instance, instance.test_42) 
+              instance.test_42()
+           setup_method(instance, instance.test_23) 
+              instance.test_23()
+       teardown_class(TestStateFullThing) 
+    teardown_module(test_setup_flow_example)
+
+
+Note that ``setup_class(TestStateFullThing)`` is called and not 
+``TestStateFullThing.setup_class()`` which would require you
+to insert ``setup_class = classmethod(setup_class)`` to make
+your setup function callable. 
 
 The three components of ``py.test``
 ===================================

Added: py/dist/example/test/test_setup_flow_example.py
==============================================================================
--- (empty file)
+++ py/dist/example/test/test_setup_flow_example.py	Thu Oct 14 20:59:31 2004
@@ -0,0 +1,42 @@
+def setup_module(module):
+    module.TestStateFullThing.classcount = 0
+
+class TestStateFullThing:
+    def setup_class(cls):
+        cls.classcount += 1
+
+    def teardown_class(cls):
+        cls.classcount -= 1
+
+    def setup_method(self, method):
+        self.id = eval(method.func_name[5:])
+
+    def test_42(self):
+        assert self.classcount == 1
+        assert self.id == 42
+
+    def test_23(self):
+        assert self.classcount == 1
+        assert self.id == 23
+
+def teardown_module(module):
+    assert module.TestStateFullThing.classcount == 0
+
+""" For this example the control flow happens as follows::
+    import test_setup_flow_example
+    setup_module(test_setup_flow_example)
+       setup_class(TestStateFullThing) 
+           instance = TestStateFullThing()
+           setup_method(instance, instance.test_42) 
+              instance.test_42()
+           setup_method(instance, instance.test_23) 
+              instance.test_23()
+       teardown_class(TestStateFullThing) 
+    teardown_module(test_setup_flow_example)
+
+Note that ``setup_class(TestStateFullThing)`` is called and not 
+``TestStateFullThing.setup_class()`` which would require you
+to insert ``setup_class = classmethod(setup_class)`` to make
+your setup function callable. 
+"""
+