- Change paster template ``tests.py`` to include a true unit test.

    Retain old test as an integration test.  Update documentation.

2 files changed, 61 insertions, 32 deletions

diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index d3d4628ff..4c2f6a9ec 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -1,33 +1,66 @@
 import unittest
 
+from zope.testing.cleanup import cleanUp
+from repoze.bfg import testing
+
 class ViewTests(unittest.TestCase):
+
+    """ These tests are unit tests for the view.  They test the
+    functionality of *only* the view.  They register and use dummy
+    implementations of repoze.bfg functionality to allow you to avoid
+    testing 'too much'"""
+
     def setUp(self):
-        # This sets up the application registry with the registrations
-        # your application declares in its configure.zcml (including
-        # dependent registrations for repoze.bfg itself).  This is a
-        # heavy-hammer way of making sure that your tests have enough
-        # context to run properly.  But tests will run faster if you
-        # use only the registrations you need programmatically, so you
-        # should explore ways to do that rather than rely on ZCML (see
-        # the repoze.bfg tests for inspiration).
-        self._cleanup()
+        """ cleanUp() is required to clear out the application registry
+        between tests (done in setUp for good measure too)
+        """
+        cleanUp()
+        
+    def tearDown(self):
+        """ cleanUp() is required to clear out the application registry
+        between tests
+        """
+        cleanUp()
+
+    def test_my_view(self):
+        from myproject.views import my_view
+        context = testing.DummyModel()
+        request = testing.DummyRequest()
+        renderer = testing.registerDummyRenderer('templates/mytemplate.pt')
+        response = my_view(context, request)
+        self.assertEqual(renderer.project, 'myproject')
+
+class ViewIntegrationTests(unittest.TestCase):
+    """ These tests are integration tests for the view.  These test
+    the functionality the view *and* its integration with the rest of
+    the repoze.bfg framework.  They cause the entire environment to be
+    set up and torn down as if your application was running 'for
+    real'.  This is a heavy-hammer way of making sure that your tests
+    have enough context to run properly, and it tests your view's
+    integration with the rest of BFG.  You should not use this style
+    of test to perform 'true' unit testing as tests will run faster
+    and will be easier to write if you use the testing facilities
+    provided by bfg and only the registrations you need, as in the
+    above ViewTests.
+    """
+    def setUp(self):
+        """ This sets up the application registry with the
+        registrations your application declares in its configure.zcml
+        (including dependent registrations for repoze.bfg itself).
+        """
+        cleanUp()
         import myproject
         import zope.configuration.xmlconfig
-        zope.configuration.xmlconfig.file('configure.zcml',
-                                          package=myproject)
+        zope.configuration.xmlconfig.file('configure.zcml', package=myproject)
 
     def tearDown(self):
-        self._cleanup()
-
-    def _cleanup(self):
-        # this clears the application registry 
-        from zope.testing.cleanup import cleanUp
+        """ Clear out the application registry """
         cleanUp()
-        
+
     def test_my_view(self):
         from myproject.views import my_view
-        context = DummyContext()
-        request = DummyRequest()
+        context = testing.DummyModel()
+        request = testing.DummyRequest()
         result = my_view(context, request)
         self.assertEqual(result.status, '200 OK')
         body = result.app_iter[0]
@@ -38,8 +71,3 @@ class ViewTests(unittest.TestCase):
         self.assertEqual(result.headerlist[1], ('Content-Length',
                                                 str(len(body))))
 
-class DummyContext:
-    pass
-
-class DummyRequest:
-    pass
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index c117d906a..bdfc0098a 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -109,14 +109,14 @@ Here's sample output from a test run::
   reading manifest file 'MyProject.egg-info/SOURCES.txt'
   writing manifest file 'MyProject.egg-info/SOURCES.txt'
   running build_ext
-  .
+  ..
   ----------------------------------------------------------------------
-  Ran 1 test in 0.647s
+  Ran 2 tests in 0.647s
 
 OK
 
 The tests are found in the ``tests.py`` module in your ``paster
-create``-generated project.  One sample test exists.
+create``-generated project.  Two sample tests exist.
 
 Runnning The Project Application
 --------------------------------
@@ -589,9 +589,10 @@ The ``tests.py`` module includes unit tests for your application.
 .. literalinclude:: MyProject/myproject/tests.py
    :linenos:
 
-This sample ``tests.py`` file has a single unit test defined within
-it.  This is the code that is executed when you run ``setup.py test
--q``.  You may add more tests here as you build your application.  You
-are not required to write tests to use :mod:`repoze.bfg`, this file is
-simply provided as convenience and example.
+This sample ``tests.py`` file has a single unit test and a single
+integration test defined within it.  These two tests are executed when
+you run ``setup.py test -q``.  You may add more tests here as you
+build your application.  You are not required to write tests to use
+:mod:`repoze.bfg`, this file is simply provided as convenience and
+example.