Advanced testing topics¶

Example¶

The following is a simple unit test using the request factory:

from django.utils import unittest
from django.test.client import RequestFactory

class SimpleTest(unittest.TestCase):
    def setUp(self):
        # Every test needs access to the request factory.
        self.factory = RequestFactory()

    def test_details(self):
        # Create an instance of a GET request.
        request = self.factory.get('/customer/details')

        # Test my_view() as if it were deployed at /customer/details
        response = my_view(request)
        self.assertEqual(response.status_code, 200)

Testing master/slave configurations¶

If you’re testing a multiple database configuration with master/slave replication, this strategy of creating test databases poses a problem. When the test databases are created, there won’t be any replication, and as a result, data created on the master won’t be seen on the slave.

To compensate for this, Django allows you to define that a database is a test mirror. Consider the following (simplified) example database configuration:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'myproject',
        'HOST': 'dbmaster',
         # ... plus some other settings
    },
    'slave': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'myproject',
        'HOST': 'dbslave',
        'TEST_MIRROR': 'default'
        # ... plus some other settings
    }
}

In this setup, we have two database servers: dbmaster, described by the database alias default, and dbslave described by the alias slave. As you might expect, dbslave has been configured by the database administrator as a read slave of dbmaster, so in normal activity, any write to default will appear on slave.

If Django created two independent test databases, this would break any tests that expected replication to occur. However, the slave database has been configured as a test mirror (using the TEST_MIRROR setting), indicating that under testing, slave should be treated as a mirror of default.

When the test environment is configured, a test version of slave will not be created. Instead the connection to slave will be redirected to point at default. As a result, writes to default will appear on slave – but because they are actually the same database, not because there is data replication between the two databases.

Controlling creation order for test databases¶

By default, Django will always create the default database first. However, no guarantees are made on the creation order of any other databases in your test setup.

If your database configuration requires a specific creation order, you can specify the dependencies that exist using the TEST_DEPENDENCIES setting. Consider the following (simplified) example database configuration:

DATABASES = {
    'default': {
         # ... db settings
         'TEST_DEPENDENCIES': ['diamonds']
    },
    'diamonds': {
        # ... db settings
    },
    'clubs': {
        # ... db settings
        'TEST_DEPENDENCIES': ['diamonds']
    },
    'spades': {
        # ... db settings
        'TEST_DEPENDENCIES': ['diamonds','hearts']
    },
    'hearts': {
        # ... db settings
        'TEST_DEPENDENCIES': ['diamonds','clubs']
    }
}

Under this configuration, the diamonds database will be created first, as it is the only database alias without dependencies. The default and clubs alias will be created next (although the order of creation of this pair is not guaranteed); then hearts; and finally spades.

If there are any circular dependencies in the TEST_DEPENDENCIES definition, an ImproperlyConfigured exception will be raised.

Defining a test runner¶

A test runner is a class defining a run_tests() method. Django ships with a DjangoTestSuiteRunner class that defines the default Django testing behavior. This class defines the run_tests() entry point, plus a selection of other methods that are used to by run_tests() to set up, execute and tear down the test suite.

class DjangoTestSuiteRunner(verbosity=1, interactive=True, failfast=True, **kwargs)¶

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.

If interactive is True, the test suite has permission to ask the user for instructions when the test suite is executed. An example of this behavior would be asking for permission to delete an existing test database. If interactive is False, the test suite must be able to run without any manual intervention.

If failfast is True, the test suite will stop running after the first test failure is detected.

Django will, from time to time, extend the capabilities of the test runner by adding new arguments. The **kwargs declaration allows for this expansion. If you subclass DjangoTestSuiteRunner or write your own test runner, ensure accept and handle the **kwargs parameter.

Your test runner may also define additional command-line options. If you add an option_list attribute to a subclassed test runner, those options will be added to the list of command-line options that the test command can use.

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 and setting up the dummy email outbox.

teardown_test_environment()¶

Performs any global post-test teardown, such as removing the black magic hooks into the template system and restoring normal email services.

The creation module of the database backend (connection.creation) also provides some utilities that can be useful during testing.

create_test_db([verbosity=1, autoclobber=False])¶

Creates a new test database and runs syncdb against it.

verbosity has the same behavior as in run_tests().

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.

Returns the name of the test database that it created.

create_test_db() has the side effect of modifying the value of NAME in DATABASES to match the name of the test database.

destroy_test_db(old_database_name[, verbosity=1])¶

Destroys the database whose name is the value of NAME in DATABASES, and sets NAME to the value of old_database_name.

The verbosity argument has the same behavior as for DjangoTestSuiteRunner.