Django doctests in views.py

Question

The Django 1.4 documentation on tests states:

For a given Django application, the test runner looks for doctests in two places:

• The models.py file. You can define module-level doctests and/or a doctest for individual models. It's common practice to put application-level doctests in the module docstring and model-level doctests in the model docstrings.

• A file called tests.py in the application directory -- i.e., the directory that holds models.py. This file is a hook for any and all doctests you want to write that aren't necessarily related to models.

Out of curiosity I'd like to know why Django's testrunner is limited to the doctests in models.py, but more practically I'd like to know how one could expand the testrunner's doctests to include (for example) views.py and other modules when running manage.py test.

I'd be grateful for any input.

Thank you.

Brian

Answer 1

You can do this by adding/editing the suite() function in tests.py which defines what tests will be run by the django test runner.

import unittest
import doctest
from project import views

def suite():
    suite = unittest.TestSuite()
    suite.addTest(doctest.DocTestSuite(views))
    return suite

Then just run your tests as usual and you should see your doctests in views.py run.

$ python manage.py test project

This is described in more detail in the django testing documentation

When you run your tests, the default behavior of the test utility is to find all the test cases (that is, subclasses of unittest.TestCase) in models.py and tests.py, automatically build a test suite out of those test cases, and run that suite.

There is a second way to define the test suite for a module: if you define a function called suite() in either models.py or tests.py, the Django test runner will use that function 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.

However, keep in mind that constructing your own test suite means that the django test runner will not automatically run any tests you have in tests.py. You'll have to add these into your suite manually, for example

import unittest
import doctest
from project import views

class FooTestCase(unittest.TestCase):
    def testFoo(self):
        self.assertEquals('foo', 'bar')

def suite():
    suite = unittest.TestSuite()
    suite.addTest(doctest.DocTestSuite(views))
    suite.addTest(unittest.TestLoader().loadTestsFromTestCase(FooTestCase))
    return suite

Answer 2

Things have changed in Django 1.6:

Doctests will no longer be automatically discovered. To integrate doctests in your test suite, follow the recommendations in the Python documentation.

So all I had to do myself was (in my_app/tests.py):

import unittest
import doctest
from my_app import views

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite(views))
    return tests