Writing doctests

Doctests use Python’s standard doctest module, which searches for tests in your docstrings. Django’s test runner looks for doctests in your models.py file, and executes any that it finds. Django will also search for a file called tests.py in the application directory (i.e., the directory that holds models.py). If a tests.py is found, it will also be searched for doctests.

You can put doctest strings on any object in your models.py, but it’s common practice to put application-level doctests in the module docstring, and model-level doctests in the docstring for each model.

For example:

from django.db import model

class Animal(models.Model):
    """
    An animal that knows how to make noise

    # Create some animals
    >>> lion = Animal.objects.create(name="lion", sound="roar")
    >>> cat = Animal.objects.create(name="cat", sound="meow")

    # Make 'em speak
    >>> lion.speak()
    'The lion says "roar"'
    >>> cat.speak()
    'The cat says "meow"'
    """

    name = models.CharField(maxlength=20)
    sound = models.CharField(maxlength=20)

    def speak(self):
        return 'The %s says "%s"' % (self.name, self.sound)

When you run your tests, the test utility will find this docstring, notice that portions of it look like an interactive Python session, and execute those lines while checking that the results match.

For more details about how doctest works, see the standard library documentation for doctest

Writing unittests

Like doctests, Django’s unit tests use a standard library module: unittest. As with doctests, Django’s test runner looks for any unit test cases defined in models.py, or in a tests.py file stored in the application directory.

An equivalent unittest test case for the above example would look like:

import unittest
from myapp.models import Animal

class AnimalTestCase(unittest.TestCase):

    def setUp(self):
        self.lion = Animal.objects.create(name="lion", sound="roar")
        self.cat = Animal.objects.create(name="cat", sound="meow")

    def testSpeaking(self):
        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 (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.

For more details about unittest, see the standard library unittest documentation.

Which should I use?

Choosing a test framework is often contentious, so Django simply supports both of the standard Python test frameworks. Choosing one is up to each developer’s personal tastes; each is supported equally. Since each test system has different benefits, the best approach is probably to use both together, picking the test system to match the type of tests you need to write.

For developers new to testing, however, this choice can seem confusing, so here are a few key differences to help you decide whether doctests or unit tests are right for you.

If you’ve been using Python for a while, doctest will probably feel more “pythonic”. It’s designed to make writing tests as easy as possible, so there’s no overhead of writing classes or methods; you simply put tests in docstrings. This gives the added advantage of given your modules automatic documentation — well-written doctests can kill both the documentation and the testing bird with a single stone.

For developers just getting started with testing, using doctests will probably get you started faster.

The unittest framework will probably feel very familiar to developers coming from Java. Since unittest is inspired by Java’s JUnit, if you’ve used testing frameworks in other languages that similarly were inspired by JUnit, unittest should also feel pretty familiar.

Since unittest is organized around classes and methods, if you need to write a bunch of tests that all share similar code, you can easily use subclass to abstract common tasks; this makes test code shorter and cleaner. There’s also support for explicit setup and/or cleanup routines, which give you a high level of control over the environment your test cases run in.

Again, remember that you can use both systems side-by-side (even in the same app). In the end, most projects will eventually end up using both; each shines in different circumstances.

Test Client

The Test Client is a simple dummy browser. It allows you to simulate GET and POST requests on a URL, and observe the response that is received. This allows you to test that the correct view is executed for a given URL, and that the view constructs the correct response.

As the response is generated, the Test Client gathers details on the Template and Context objects that were used to generate the response. These Templates and Contexts are then provided as part of the response, and can be used as test conditions.

import unittest
from django.test.client import Client

class SimpleTest(unittest.TestCase):
    def setUp(self):
        # Every test needs a client
        self.client = Client()
    def test_details(self):
        # Issue a GET request
        response = self.client.get('/customer/details/')

        # Check that the respose is 200 OK
        self.failUnlessEqual(response.status_code, 200)
        # Check that the rendered context contains 5 customers
        self.failUnlessEqual(len(response.context['customers']), 5)

Fixtures

A test case for a database-backed website isn’t much use if there isn’t any data in the database. To make it easy to put test data into the database, Django provides a fixtures framework.

A Fixture is a collection of files that contain the serialized contents of the database. Each fixture has a unique name; however, the files that comprise the fixture can be distributed over multiple directories, in multiple applications.

However, for the purposes of unit testing, each test must be able to guarantee the contents of the database at the start of each and every test. To do this, Django provides a TestCase baseclass that can integrate with fixtures.

Moving from a normal unittest TestCase to a Django TestCase is easy - just change the base class of your test, and define a list of fixtures to be used. For example, the test case from Writing unittests would look like:

from django.test import TestCase
from myapp.models import Animal

class AnimalTestCase(TestCase):
    fixtures = ['mammals.json', 'birds']

    def setUp(self):
        # test definitions as before

At the start of each test case, before setUp() is run, Django will flush the database, returning the database the state it was in directly after syncdb was called. Then, all the named fixtures are installed. In this example, any JSON fixture called mammals, and any fixture named birds will be installed. See the documentation on loading fixtures for more details on defining and installing fixtures.

This flush/load procedure is repeated for each test in the test case, so you can be certain that the outcome of a test will not be affected by another test, or the order of test execution.

Defining a test runner

By convention, a test runner should be called run_tests; however, you can call it anything you want. The only requirement is that it accept two arguments:

run_tests(module_list, verbosity=1)

The module list is the list of Python modules that contain the models to be tested. This is the same format returned by django.db.models.get_apps()

Verbosity determines the amount of notification and debug information that will be printed to the console; 0 is no output, 1 is normal output, and 2 is verbose output.

This method should return the number of tests that failed.

Testing utilities

To assist in the creation of your own test runner, Django provides a number of utility methods in the django.test.utils module.

setup_test_environment()

Performs any global pre-test setup, such as the installing the instrumentation of the template rendering system.

teardown_test_environment()

Performs any global post-test teardown, such as removing the instrumentation of the template rendering system.

create_test_db(verbosity=1, autoclobber=False)

Creates a new test database, and run syncdb against it.

verbosity has the same behavior as in the test runner.

Autoclobber describes the behavior that will occur if a database with the same name as the test database is discovered. If autoclobber is False, the user will be asked to approve destroying the existing database. sys.exit is called if the user does not approve. If autoclobber is True, the database will be destroyed without consulting the user.

create_test_db() has the side effect of modifying settings.DATABASE_NAME to match the name of the test database.

destroy_test_db(old_database_name, verbosity=1)

Destroys the database with the name settings.DATABASE_NAME matching, and restores the value of settings.DATABASE_NAME to the provided name.

verbosity has the same behavior as in the test runner.