Advanced testing topics

The request factory

• class RequestFactory
• The RequestFactory shares the same API asthe test client. However, instead of behaving like a browser, theRequestFactory provides a way to generate a request instance that canbe used as the first argument to any view. This means you can test aview function the same way as you would test any other function – asa black box, with exactly known inputs, testing for specific outputs.

The API for the RequestFactory is a slightlyrestricted subset of the test client API:

• It only has access to the HTTP methods get(),post(), put(),delete(), head(),options(), and trace().
• These methods accept all the same arguments except forfollow. Since this is just a factory for producingrequests, it’s up to you to handle the response.
• It does not support middleware. Session and authenticationattributes must be supplied by the test itself if requiredfor the view to function properly.

Example

The following is a unit test using the request factory:

from django.contrib.auth.models import AnonymousUser, User
from django.test import RequestFactory, TestCase
 
from .views import MyView, my_view
 
class SimpleTest(TestCase):
    def setUp(self):
        # Every test needs access to the request factory.
        self.factory = RequestFactory()
        self.user = User.objects.create_user(
            username='jacob', email='jacob@…', password='top_secret')
 
    def test_details(self):
        # Create an instance of a GET request.
        request = self.factory.get('/customer/details')
 
        # Recall that middleware are not supported. You can simulate a
        # logged-in user by setting request.user manually.
        request.user = self.user
 
        # Or you can simulate an anonymous user by setting request.user to
        # an AnonymousUser instance.
        request.user = AnonymousUser()
 
        # Test my_view() as if it were deployed at /customer/details
        response = my_view(request)
        # Use this syntax for class-based views.
        response = MyView.as_view()(request)
        self.assertEqual(response.status_code, 200)

Tests and multiple host names

The ALLOWED_HOSTS setting is validated when running tests. Thisallows the test client to differentiate between internal and external URLs.

Projects that support multitenancy or otherwise alter business logic based onthe request’s host and use custom host names in tests must include those hostsin ALLOWED_HOSTS.

The first option to do so is to add the hosts to your settings file. Forexample, the test suite for docs.djangoproject.com includes the following:

from django.test import TestCase
 
class SearchFormTestCase(TestCase):
    def test_empty_get(self):
        response = self.client.get('/en/dev/search/', HTTP_HOST='docs.djangoproject.dev:8000')
        self.assertEqual(response.status_code, 200)

and the settings file includes a list of the domains supported by the project:

ALLOWED_HOSTS = [
    'www.djangoproject.dev',
    'docs.djangoproject.dev',
    ...
]

Another option is to add the required hosts to ALLOWED_HOSTS usingoverride_settings() ormodify_settings(). This option may bepreferable in standalone apps that can’t package their own settings file orfor projects where the list of domains is not static (e.g., subdomains formultitenancy). For example, you could write a test for the domainhttp://otherserver/ as follows:

from django.test import TestCase, override_settings
 
class MultiDomainTestCase(TestCase):
    @override_settings(ALLOWED_HOSTS=['otherserver'])
    def test_other_domain(self):
        response = self.client.get('http://otherserver/foo/bar/')

Disabling ALLOWED_HOSTS checking (ALLOWED_HOSTS = ['*']) whenrunning tests prevents the test client from raising a helpful error message ifyou follow a redirect to an external URL.

Tests and multiple databases

Testing primary/replica configurations

If you’re testing a multiple database configuration with primary/replica(referred to as master/slave by some databases) replication, this strategy ofcreating 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 primary won’t be seen on thereplica.

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

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'myproject',
        'HOST': 'dbprimary',
         # ... plus some other settings
    },
    'replica': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'myproject',
        'HOST': 'dbreplica',
        'TEST': {
            'MIRROR': 'default',
        },
        # ... plus some other settings
    }
}

In this setup, we have two database servers: dbprimary, describedby the database alias default, and dbreplica described by thealias replica. As you might expect, dbreplica has been configuredby the database administrator as a read replica of dbprimary, so innormal activity, any write to default will appear on replica.

If Django created two independent test databases, this would break anytests that expected replication to occur. However, the replicadatabase has been configured as a test mirror (using theMIRROR test setting), indicating that undertesting, replica should be treated as a mirror of default.

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

Controlling creation order for test databases

By default, Django will assume all databases depend on the defaultdatabase and therefore always create the default database first.However, no guarantees are made on the creation order of any otherdatabases in your test setup.

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

DATABASES = {
    'default': {
        # ... db settings
        'TEST': {
            'DEPENDENCIES': ['diamonds'],
        },
    },
    'diamonds': {
        # ... db settings
        'TEST': {
            'DEPENDENCIES': [],
        },
    },
    '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 andclubs alias will be created next (although the order of creation of thispair is not guaranteed), then hearts, and finally spades.

If there are any circular dependencies in the DEPENDENCIES definition, anImproperlyConfigured exception will be raised.

Advanced features of TransactionTestCase

• TransactionTestCase.available_apps

Warning

This attribute is a private API. It may be changed or removed withouta deprecation period in the future, for instance to accommodate changesin application loading.

It’s used to optimize Django’s own test suite, which contains hundredsof models but no relations between models in different applications.

By default, available_apps is set to None. After each test, Djangocalls flush to reset the database state. This empties all tablesand emits the post_migrate signal, whichrecreates one content type and four permissions for each model. Thisoperation gets expensive proportionally to the number of models.

Setting available_apps to a list of applications instructs Django tobehave as if only the models from these applications were available. Thebehavior of TransactionTestCase changes as follows:

• post_migrate is fired before eachtest to create the content types and permissions for each model inavailable apps, in case they’re missing.
• After each test, Django empties only tables corresponding to models inavailable apps. However, at the database level, truncation may cascade torelated models in unavailable apps. Furthermorepost_migrate isn’t fired; it will befired by the next TransactionTestCase, after the correct set ofapplications is selected.Since the database isn’t fully flushed, if a test creates instances ofmodels not included in available_apps, they will leak and they maycause unrelated tests to fail. Be careful with tests that use sessions;the default session engine stores them in the database.

Since post_migrate isn’t emitted afterflushing the database, its state after a TransactionTestCase isn’t thesame as after a TestCase: it’s missing the rows created by listenersto post_migrate. Considering theorder in which tests are executed, this isn’t anissue, provided either all TransactionTestCase in a given test suitedeclare available_apps, or none of them.

available_apps is mandatory in Django’s own test suite.

• TransactionTestCase.reset_sequences
• Setting reset_sequences = True on a TransactionTestCase will makesure sequences are always reset before the test run:

class TestsThatDependsOnPrimaryKeySequences(TransactionTestCase):
    reset_sequences = True
 
    def test_animal_pk(self):
        lion = Animal.objects.create(name="lion", sound="roar")
        # lion.pk is guaranteed to always be 1
        self.assertEqual(lion.pk, 1)

Unless you are explicitly testing primary keys sequence numbers, it isrecommended that you do not hard code primary key values in tests.

Using reset_sequences = True will slow down the test, since the primarykey reset is a relatively expensive database operation.

Using the Django test runner to test reusable applications

If you are writing a reusable applicationyou may want to use the Django test runner to run your own test suiteand thus benefit from the Django testing infrastructure.

A common practice is a tests directory next to the application code, with thefollowing structure:

runtests.py
polls/
    __init__.py
    models.py
    ...
tests/
    __init__.py
    models.py
    test_settings.py
    tests.py

Let’s take a look inside a couple of those files:

runtests.py

#!/usr/bin/env python
import os
import sys
 
import django
from django.conf import settings
from django.test.utils import get_runner
 
if __name__ == "__main__":
    os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.test_settings'
    django.setup()
    TestRunner = get_runner(settings)
    test_runner = TestRunner()
    failures = test_runner.run_tests(["tests"])
    sys.exit(bool(failures))

This is the script that you invoke to run the test suite. It sets up theDjango environment, creates the test database and runs the tests.

For the sake of clarity, this example contains only the bare minimumnecessary to use the Django test runner. You may want to addcommand-line options for controlling verbosity, passing in specific testlabels to run, etc.

tests/test_settings.py

SECRET_KEY = 'fake-key'
INSTALLED_APPS = [
    "tests",
]

This file contains the Django settingsrequired to run your app’s tests.

Again, this is a minimal example; your tests may require additionalsettings to run.

Since the tests package is included in INSTALLED_APPS whenrunning your tests, you can define test-only models in its models.pyfile.

Using different testing frameworks

Clearly, unittest is not the only Python testing framework. While Djangodoesn’t provide explicit support for alternative frameworks, it does provide away to invoke tests constructed for an alternative framework as if they werenormal Django tests.

When you run ./manage.py test, Django looks at the TEST_RUNNERsetting to determine what to do. By default, TEST_RUNNER points to'django.test.runner.DiscoverRunner'. This class defines the default Djangotesting behavior. This behavior involves:

• Performing global pre-test setup.
• Looking for tests in any file below the current directory whose name matchesthe pattern test*.py.
• Creating the test databases.
• Running migrate to install models and initial data into the testdatabases.
• Running the system checks.
• Running the tests that were found.
• Destroying the test databases.
• Performing global post-test teardown.If you define your own test runner class and point TEST_RUNNER atthat class, Django will execute your test runner whenever you run./manage.py test. In this way, it is possible to use any test frameworkthat can be executed from Python code, or to modify the Django test executionprocess to satisfy whatever testing requirements you may have.

Defining a test runner

A test runner is a class defining a run_tests() method. Django shipswith a DiscoverRunner class that defines the default Django testingbehavior. This class defines the run_tests() entry point, plus aselection of other methods that are used to by run_tests() to set up,execute and tear down the test suite.

• class DiscoverRunner(pattern='test*.py', top_level=None, verbosity=1, interactive=True, failfast=False, keepdb=False, reverse=False, debug_mode=False, debug_sql=False, test_name_patterns=None, **kwargs)
• DiscoverRunner will search for tests in any file matching pattern.

top_level can be used to specify the directory containing yourtop-level Python modules. Usually Django can figure this out automatically,so it’s not necessary to specify this option. If specified, it shouldgenerally be the directory containing your manage.py file.

verbosity determines the amount of notification and debug informationthat will be printed to the console; 0 is no output, 1 is normaloutput, and 2 is verbose output.

If interactive is True, the test suite has permission to ask theuser for instructions when the test suite is executed. An example of thisbehavior would be asking for permission to delete an existing testdatabase. If interactive is False, the test suite must be able torun without any manual intervention.

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

If keepdb is True, the test suite will use the existing database,or create one if necessary. If False, a new database will be created,prompting the user to remove the existing one, if present.

If reverse is True, test cases will be executed in the oppositeorder. This could be useful to debug tests that aren’t properly isolatedand have side effects. Grouping by test class ispreserved when using this option.

debug_mode specifies what the DEBUG setting should beset to prior to running tests.

If debug_sql is True, failing test cases will output SQL querieslogged to the django.db.backends logger as wellas the traceback. If verbosity is 2, then queries in all tests areoutput.

test_name_patterns can be used to specify a set of patterns forfiltering test methods and classes by their names.

Django may, from time to time, extend the capabilities of the test runnerby adding new arguments. The kwargs declaration allows for thisexpansion. If you subclass DiscoverRunner or write your own testrunner, ensure it accepts kwargs.

Your test runner may also define additional command-line options.Create or override an add_arguments(cls, parser) class method and addcustom arguments by calling parser.add_argument() inside the method, sothat the test command will be able to use those arguments.

Attributes

• DiscoverRunner.test_suite

• The class used to build the test suite. By default it is set tounittest.TestSuite. This can be overridden if you wish to implementdifferent logic for collecting tests.

• DiscoverRunner.test_runner

• This is the class of the low-level test runner which is used to executethe individual tests and format the results. By default it is set tounittest.TextTestRunner. Despite the unfortunate similarity innaming conventions, this is not the same type of class asDiscoverRunner, which covers a broader set of responsibilities. Youcan override this attribute to modify the way tests are run and reported.

• DiscoverRunner.test_loader

• This is the class that loads tests, whether from TestCases or modules orotherwise and bundles them into test suites for the runner to execute.By default it is set to unittest.defaultTestLoader. You can overridethis attribute if your tests are going to be loaded in unusual ways.

Methods

• DiscoverRunner.runtests(_test_labels, extra_tests=None, **kwargs)
• Run the test suite.

test_labels allows you to specify which tests to run and supportsseveral formats (see DiscoverRunner.build_suite() for a list ofsupported formats).

extra_tests is a list of extra TestCase instances to add to thesuite that is executed by the test runner. These extra tests are runin addition to those discovered in the modules listed in test_labels.

This method should return the number of tests that failed.

• classmethod DiscoverRunner.addarguments(_parser)

• Override this class method to add custom arguments accepted by thetest management command. Seeargparse.ArgumentParser.add_argument() for details about addingarguments to a parser.

• DiscoverRunner.setuptest_environment(**kwargs_)

• Sets up the test environment by callingsetup_test_environment() and settingDEBUG to self.debug_mode (defaults to False).

• DiscoverRunner.buildsuite(_test_labels, extra_tests=None, **kwargs)

• Constructs a test suite that matches the test labels provided.

test_labels is a list of strings describing the tests to be run. A testlabel can take one of four forms:

• path.to.test_module.TestCase.test_method – Run a single test methodin a test case.
• path.to.test_module.TestCase – Run all the test methods in a testcase.
• path.to.module – Search for and run all tests in the named Pythonpackage or module.
• path/to/directory – Search for and run all tests below the nameddirectory.If test_labels has a value of None, the test runner will search fortests in all files below the current directory whose names match itspattern (see above).

extra_tests is a list of extra TestCase instances to add to thesuite that is executed by the test runner. These extra tests are runin addition to those discovered in the modules listed in test_labels.

Returns a TestSuite instance ready to be run.

• DiscoverRunner.setupdatabases(**kwargs_)

• Creates the test databases by callingsetup_databases().

• DiscoverRunner.run_checks()

• Runs the system checks.

• DiscoverRunner.runsuite(_suite, **kwargs)

• Runs the test suite.

Returns the result produced by the running the test suite.

• DiscoverRunner.get_test_runner_kwargs()

• Returns the keyword arguments to instantiate theDiscoverRunner.test_runner with.

• DiscoverRunner.teardowndatabases(_old_config, **kwargs)

• Destroys the test databases, restoring pre-test conditions by callingteardown_databases().

• DiscoverRunner.teardowntest_environment(**kwargs_)

• Restores the pre-test environment.

• DiscoverRunner.suiteresult(_suite, result, **kwargs)

• Computes and returns a return code based on a test suite, and the resultfrom that test suite.

Testing utilities

django.test.utils

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

• setuptest_environment(_debug=None)
• Performs global pre-test setup, such as installing instrumentation for thetemplate rendering system and setting up the dummy email outbox.

If debug isn’t None, the DEBUG setting is updated to itsvalue.

• teardown_test_environment()

• Performs global post-test teardown, such as removing instrumentation fromthe template system and restoring normal email services.

• setupdatabases(_verbosity, interactive, keepdb=False, debug_sql=False, parallel=0, aliases=None, **kwargs)

• Creates the test databases.

Returns a data structure that provides enough detail to undo the changesthat have been made. This data will be provided to theteardown_databases() function at the conclusion of testing.

The aliases argument determines which DATABASES aliases testdatabases should be setup for. If it’s not provided, it defaults to all ofDATABASES aliases.

New in Django 2.2:The aliases argument was added.

• teardowndatabases(_old_config, parallel=0, keepdb=False)
• Destroys the test databases, restoring pre-test conditions.

old_config is a data structure defining the changes in the databaseconfiguration that need to be reversed. It’s the return value of thesetup_databases() method.

django.db.connection.creation

The creation module of the database backend also provides some utilities thatcan be useful during testing.

• createtest_db(_verbosity=1, autoclobber=False, serialize=True, keepdb=False)
• Creates a new test database and runs migrate against it.

verbosity has the same behavior as in run_tests().

autoclobber describes the behavior that will occur if adatabase with the same name as the test database is discovered:

• If autoclobber is False, the user will be asked toapprove destroying the existing database. sys.exit iscalled if the user does not approve.
• If autoclobber is True, the database will be destroyedwithout consulting the user.serialize determines if Django serializes the database into anin-memory JSON string before running tests (used to restore the databasestate between tests if you don’t have transactions). You can set this toFalse to speed up creation time if you don’t have any test classeswith serialized_rollback=True.

If you are using the default test runner, you can control this with thethe SERIALIZE entry in the TEST dictionary.

keepdb determines if the test run should use an existingdatabase, or create a new one. If True, the existingdatabase will be used, or created if not present. If False,a new database will be created, prompting the user to removethe existing one, if present.

Returns the name of the test database that it created.

create_test_db() has the side effect of modifying the value ofNAME in DATABASES to match the name of the testdatabase.

• destroytest_db(_old_database_name, verbosity=1, keepdb=False)
• Destroys the database whose name is the value of NAME inDATABASES, and sets NAME to the value ofold_database_name.

The verbosity argument has the same behavior as forDiscoverRunner.

If the keepdb argument is True, then the connection to thedatabase will be closed, but the database will not be destroyed.

Integration with coverage.py

Code coverage describes how much source code has been tested. It shows whichparts of your code are being exercised by tests and which are not. It’s animportant part of testing applications, so it’s strongly recommended to checkthe coverage of your tests.

Django can be easily integrated with coverage.py, a tool for measuring codecoverage of Python programs. First, install coverage.py. Next, run thefollowing from your project folder containing manage.py:

coverage run --source='.' manage.py test myapp

This runs your tests and collects coverage data of the executed files in yourproject. You can see a report of this data by typing following command:

coverage report

Note that some Django code was executed while running tests, but it is notlisted here because of the source flag passed to the previous command.

For more options like annotated HTML listings detailing missed lines, see thecoverage.py docs.