Fixed #3782 -- Added support for the suite() method recommended by the Python unittest docs. Thanks for the suggestion, rene.puls@repro-mayr.de.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5729 bcc190cf-cafb-0310-a4f2-bffc1f526a37

django/test/simple.py

@@ -14,7 +14,11 @@ def build_suite(app_module):
     "Create a complete Django test suite for the provided application module"
     suite = unittest.TestSuite()
     
-    # Load unit and doctests in the models.py file
+    # Load unit and doctests in the models.py module. If module has
+    # a suite() method, use it. Otherwise build the test suite ourselves.
+    if hasattr(app_module, 'suite'):
+        suite.addTest(app_module.suite())
+    else:
         suite.addTest(unittest.defaultTestLoader.loadTestsFromModule(app_module))
         try:
             suite.addTest(doctest.DocTestSuite(app_module,
@@ -30,6 +34,11 @@ def build_suite(app_module):
         app_path = app_module.__name__.split('.')[:-1]
         test_module = __import__('.'.join(app_path + [TEST_MODULE]), {}, {}, TEST_MODULE)
         
+        # Load unit and doctests in the tests.py module. If module has
+        # a suite() method, use it. Otherwise build the test suite ourselves.
+        if hasattr(test_module, 'suite'):
+            suite.addTest(test_module.suite())
+        else:
             suite.addTest(unittest.defaultTestLoader.loadTestsFromModule(test_module))
             try:            
                 suite.addTest(doctest.DocTestSuite(test_module, 

docs/testing.txt

@@ -118,10 +118,16 @@ An equivalent unittest test case for the above example would look like::
             self.assertEquals(self.lion.speak(), 'The lion says "roar"')
             self.assertEquals(self.cat.speak(), 'The cat says "meow"')
 
-When you `run your tests`_, the test utility will find all the test cases
+When you `run your tests`_, the default behavior of the test utility is
-(that is, subclasses of ``unittest.TestCase``) in ``models.py`` and
+to find all the test cases (that is, subclasses of ``unittest.TestCase``)
-``tests.py``, automatically build a test suite out of those test cases,
+in ``models.py`` and ``tests.py``, automatically build a test suite out of
-and run that suite.
+those test cases, and run that suite.
+
+However, if you define a method called ``suite()`` in either ``models.py`` or
+``tests.py``, that method will be used to construct the test suite for that
+module. This follows the `suggested organization`_ for unit tests. See the
+Python documentation for more details on how to construct a complex test
+suite.
 
 For more details about ``unittest``, see the `standard library unittest
 documentation`_.
@@ -129,6 +135,7 @@ documentation`_.
 .. _unittest: http://docs.python.org/lib/module-unittest.html
 .. _standard library unittest documentation: unittest_
 .. _run your tests: `Running tests`_
+.. _suggested organization: http://docs.python.org/lib/organizing-tests.html
 
 Which should I use?
 -------------------

tests/modeltests/test_client/tests.py

@@ -0,0 +1,20 @@
+# Validate that you can override the default test suite
+
+import unittest
+
+def suite():
+    """
+    Define a suite that deliberately ignores a test defined in
+    this module.
+    """
+    
+    testSuite = unittest.TestSuite()
+    testSuite.addTest(SampleTests('testGoodStuff'))
+    return testSuite
+    
+class SampleTests(unittest.TestCase):
+    def testGoodStuff(self):
+        pass
+        
+    def testBadStuff(self):
+        self.fail("This test shouldn't run")