Testing tools

Testing tools

Django provides a small set of tools that come in handy when writing tests.

The test client

The test client is a Python class that acts as a dummy Web browser, allowingyou to test your views and interact with your Django-powered applicationprogrammatically.

Some of the things you can do with the test client are:

Simulate GET and POST requests on a URL and observe the response –everything from low-level HTTP (result headers and status codes) topage content.
See the chain of redirects (if any) and check the URL and status code ateach step.
Test that a given request is rendered by a given Django template, witha template context that contains certain values.Note that the test client is not intended to be a replacement for Selenium orother “in-browser” frameworks. Django’s test client has a different focus. Inshort:
Use Django’s test client to establish that the correct template is beingrendered and that the template is passed the correct context data.
Use in-browser frameworks like Selenium to test rendered HTML and thebehavior of Web pages, namely JavaScript functionality. Django alsoprovides special support for those frameworks; see the section onLiveServerTestCase for more details.A comprehensive test suite should use a combination of both test types.

Overview and a quick example

To use the test client, instantiate django.test.Client and retrieveWeb pages:

>>> from django.test import Client
>>> c = Client()
>>> response = c.post('/login/', {'username': 'john', 'password': 'smith'})
>>> response.status_code
200
>>> response = c.get('/customer/details/')
>>> response.content
b'<!DOCTYPE html...'

As this example suggests, you can instantiate Client from within a sessionof the Python interactive interpreter.

Note a few important things about how the test client works:

The test client does not require the Web server to be running. In fact,it will run just fine with no Web server running at all! That’s becauseit avoids the overhead of HTTP and deals directly with the Djangoframework. This helps make the unit tests run quickly.
When retrieving pages, remember to specify the path of the URL, not thewhole domain. For example, this is correct:

>>> c.get('/login/')

This is incorrect:

>>> c.get('https://www.example.com/login/')

The test client is not capable of retrieving Web pages that are notpowered by your Django project. If you need to retrieve other Web pages,use a Python standard library module such as urllib.

To resolve URLs, the test client uses whatever URLconf is pointed-to byyour ROOT_URLCONF setting.
Although the above example would work in the Python interactiveinterpreter, some of the test client’s functionality, notably thetemplate-related functionality, is only available while tests arerunning.

The reason for this is that Django’s test runner performs a bit of blackmagic in order to determine which template was loaded by a given view.This black magic (essentially a patching of Django’s template system inmemory) only happens during test running.

By default, the test client will disable any CSRF checksperformed by your site.

If, for some reason, you want the test client to perform CSRFchecks, you can create an instance of the test client thatenforces CSRF checks. To do this, pass in theenforce_csrf_checks argument when you construct yourclient:

>>> from django.test import Client
>>> csrf_client = Client(enforce_csrf_checks=True)

Making requests

Use the django.test.Client class to make requests.

class Client(enforce_csrf_checks=False, json_encoder=DjangoJSONEncoder, **defaults)
It requires no arguments at time of construction. However, you can usekeywords arguments to specify some default headers. For example, this willsend a User-Agent HTTP header in each request:

>>> c = Client(HTTP_USER_AGENT='Mozilla/5.0')

The values from the extra keywords arguments passed toget(),post(), etc. have precedence overthe defaults passed to the class constructor.

The enforce_csrf_checks argument can be used to test CSRFprotection (see above).

The json_encoder argument allows setting a custom JSON encoder forthe JSON serialization that’s described in post().

The raise_request_exception argument allows controlling whether or notexceptions raised during the request should also be raised in the test.Defaults to True.

New in Django 3.0:The raise_request_exception argument was added.

Once you have a Client instance, you can call any of the followingmethods:

get(path, data=None, follow=False, secure=False, **extra)
Makes a GET request on the provided path and returns a Responseobject, which is documented below.

The key-value pairs in the data dictionary are used to create a GETdata payload. For example:

>>> c = Client()
>>> c.get('/customers/details/', {'name': 'fred', 'age': 7})

…will result in the evaluation of a GET request equivalent to:

/customers/details/?name=fred&age=7

The extra keyword arguments parameter can be used to specifyheaders to be sent in the request. For example:

>>> c = Client()
>>> c.get('/customers/details/', {'name': 'fred', 'age': 7},
...       HTTP_X_REQUESTED_WITH='XMLHttpRequest')

…will send the HTTP header HTTP_X_REQUESTED_WITH to thedetails view, which is a good way to test code paths that use thedjango.http.HttpRequest.is_ajax() method.

CGI specification

The headers sent via **extra should follow CGI specification.For example, emulating a different “Host” header as sent in theHTTP request from the browser to the server should be passedas HTTP_HOST.

If you already have the GET arguments in URL-encoded form, you canuse that encoding instead of using the data argument. For example,the previous GET request could also be posed as:

>>> c = Client()
>>> c.get('/customers/details/?name=fred&age=7')

If you provide a URL with both an encoded GET data and a data argument,the data argument will take precedence.

If you set follow to True the client will follow any redirectsand a redirect_chain attribute will be set in the response objectcontaining tuples of the intermediate urls and status codes.

If you had a URL /redirect_me/ that redirected to /next/, thatredirected to /final/, this is what you’d see:

>>> response = c.get('/redirect_me/', follow=True)
>>> response.redirect_chain
[('http://testserver/next/', 302), ('http://testserver/final/', 302)]

If you set secure to True the client will emulate an HTTPSrequest.

post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, **extra)
Makes a POST request on the provided path and returns aResponse object, which is documented below.

The key-value pairs in the data dictionary are used to submit POSTdata. For example:

>>> c = Client()
>>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})

…will result in the evaluation of a POST request to this URL:

/login/

…with this POST data:

name=fred&passwd=secret

If you provide contenttype as _application/json, thedata is serialized using json.dumps() if it’s a dict, list,or tuple. Serialization is performed withDjangoJSONEncoder by default,and can be overridden by providing a json_encoder argument toClient. This serialization also happens for put(),patch(), and delete() requests.

Changed in Django 2.2:The JSON serialization was extended to support lists and tuples. Inolder versions, only dicts are serialized.

If you provide any other content_type (e.g. _text/xml_for an XML payload), the contents of data are sent as-is in thePOST request, using content_type in the HTTP Content-Typeheader.

If you don’t provide a value for contenttype, the values indata will be transmitted with a content type of_multipart/form-data. In this case, the key-value pairs indata will be encoded as a multipart message and used to create thePOST data payload.

To submit multiple values for a given key – for example, to specifythe selections for a <select multiple> – provide the values as alist or tuple for the required key. For example, this value of datawould submit three selected values for the field named choices:

{'choices': ('a', 'b', 'd')}

Submitting files is a special case. To POST a file, you need onlyprovide the file field name as a key, and a file handle to the file youwish to upload as a value. For example:

>>> c = Client()
>>> with open('wishlist.doc') as fp:
...     c.post('/customers/wishes/', {'name': 'fred', 'attachment': fp})

(The name attachment here is not relevant; use whatever name yourfile-processing code expects.)

You may also provide any file-like object (e.g., StringIO orBytesIO) as a file handle. If you’re uploading to anImageField, the object needs a nameattribute that passes thevalidate_image_file_extension validator.For example:

>>> from io import BytesIO
>>> img = BytesIO(b'mybinarydata')
>>> img.name = 'myimage.jpg'

Note that if you wish to use the same file handle for multiplepost() calls then you will need to manually reset the filepointer between posts. The easiest way to do this is tomanually close the file after it has been provided topost(), as demonstrated above.

You should also ensure that the file is opened in a way thatallows the data to be read. If your file contains binary datasuch as an image, this means you will need to open the file inrb (read binary) mode.

The extra argument acts the same as for Client.get().

If the URL you request with a POST contains encoded parameters, theseparameters will be made available in the request.GET data. For example,if you were to make the request:

>>> c.post('/login/?visitor=true', {'name': 'fred', 'passwd': 'secret'})

… the view handling this request could interrogate request.POSTto retrieve the username and password, and could interrogate request.GETto determine if the user was a visitor.

If you set follow to True the client will follow any redirectsand a redirect_chain attribute will be set in the response objectcontaining tuples of the intermediate urls and status codes.

If you set secure to True the client will emulate an HTTPSrequest.

head(path, data=None, follow=False, secure=False, **extra)
Makes a HEAD request on the provided path and returns aResponse object. This method works just like Client.get(),including the follow, secure and extra arguments, exceptit does not return a message body.
options(path, data='', content_type='application/octet-stream', follow=False, secure=False, **extra)
Makes an OPTIONS request on the provided path and returns aResponse object. Useful for testing RESTful interfaces.

When data is provided, it is used as the request body, anda Content-Type header is set to content_type.

The follow, secure and extra arguments act the same as forClient.get().

put(path, data='', content_type='application/octet-stream', follow=False, secure=False, **extra)
Makes a PUT request on the provided path and returns aResponse object. Useful for testing RESTful interfaces.

When data is provided, it is used as the request body, anda Content-Type header is set to content_type.

The follow, secure and extra arguments act the same as forClient.get().

patch(path, data='', content_type='application/octet-stream', follow=False, secure=False, **extra)
Makes a PATCH request on the provided path and returns aResponse object. Useful for testing RESTful interfaces.

The follow, secure and extra arguments act the same as forClient.get().

delete(path, data='', content_type='application/octet-stream', follow=False, secure=False, **extra)
Makes a DELETE request on the provided path and returns aResponse object. Useful for testing RESTful interfaces.

When data is provided, it is used as the request body, anda Content-Type header is set to content_type.

The follow, secure and extra arguments act the same as forClient.get().

trace(path, follow=False, secure=False, **extra)
Makes a TRACE request on the provided path and returns aResponse object. Useful for simulating diagnostic probes.

Unlike the other request methods, data is not provided as a keywordparameter in order to comply with RFC 7231#section-4.3.8, whichmandates that TRACE requests must not have a body.

The follow, secure, and extra arguments act the same as forClient.get().

login(**credentials)
If your site uses Django’s authentication systemand you deal with logging in users, you can use the test client’slogin() method to simulate the effect of a user logging into thesite.

After you call this method, the test client will have all the cookiesand session data required to pass any login-based tests that may formpart of a view.

The format of the credentials argument depends on whichauthentication backend you’re using(which is configured by your AUTHENTICATION_BACKENDSsetting). If you’re using the standard authentication backend providedby Django (ModelBackend), credentials should be the user’susername and password, provided as keyword arguments:

>>> c = Client()
>>> c.login(username='fred', password='secret')
 
# Now you can access a view that's only available to logged-in users.

If you’re using a different authentication backend, this method mayrequire different credentials. It requires whichever credentials arerequired by your backend’s authenticate() method.

login() returns True if it the credentials were accepted andlogin was successful.

Finally, you’ll need to remember to create user accounts before you canuse this method. As we explained above, the test runner is executedusing a test database, which contains no users by default. As a result,user accounts that are valid on your production site will not workunder test conditions. You’ll need to create users as part of the testsuite – either manually (using the Django model API) or with a testfixture. Remember that if you want your test user to have a password,you can’t set the user’s password by setting the password attributedirectly – you must use theset_password() function tostore a correctly hashed password. Alternatively, you can use thecreate_user() helpermethod to create a new user with a correctly hashed password.

forcelogin(_user, backend=None)
If your site uses Django’s authenticationsystem, you can use the force_login() methodto simulate the effect of a user logging into the site. Use this methodinstead of login() when a test requires a user be logged in andthe details of how a user logged in aren’t important.

Unlike login(), this method skips the authentication andverification steps: inactive users (is_active=False) are permitted to loginand the user’s credentials don’t need to be provided.

The user will have its backend attribute set to the value of thebackend argument (which should be a dotted Python path string), orto settings.AUTHENTICATION_BACKENDS[0] if a value isn’t provided.The authenticate() function called bylogin() normally annotates the user like this.

This method is faster than login() since the expensivepassword hashing algorithms are bypassed. Also, you can speed uplogin() by using a weaker hasher while testing.

logout()
If your site uses Django’s authentication system,the logout() method can be used to simulate the effect of a userlogging out of your site.

After you call this method, the test client will have all the cookiesand session data cleared to defaults. Subsequent requests will appearto come from an AnonymousUser.

Testing responses

The get() and post() methods both return a Response object. ThisResponse object is not the same as the HttpResponse object returnedby Django views; the test response object has some additional data useful fortest code to verify.

Specifically, a Response object has the following attributes:

class Response
- client
- The test client that was used to make the request that resulted in theresponse.
- content
- The body of the response, as a bytestring. This is the final pagecontent as rendered by the view, or any error message.
- context
- The template Context instance that was used to render the template thatproduced the response content.

If the rendered page used multiple templates, then context will be alist of Context objects, in the order in which they were rendered.

Regardless of the number of templates used during rendering, you canretrieve context values using the [] operator. For example, thecontext variable name could be retrieved using:

>>> response = client.get('/foo/')
>>> response.context['name']
'Arthur'

Not using Django templates?

This attribute is only populated when using theDjangoTemplates backend.If you’re using another template engine,context_datamay be a suitable alternative on responses with that attribute.

exc_info
New in Django 3.0:

A tuple of three values that provides information about the unhandledexception, if any, that occurred during the view.

The values are (type, value, traceback), the same as returned byPython’s sys.exc_info(). Their meanings are:

- _type_: The type of the exception.
- _value_: The exception instance.
- _traceback_: A traceback object which encapsulates the call stack atthe point where the exception originally occurred.

If no exception occurred, then exc_info will be None.

json(**kwargs)
The body of the response, parsed as JSON. Extra keyword arguments arepassed to json.loads(). For example:

>>> response = client.get('/foo/')
>>> response.json()['name']
'Arthur'

If the Content-Type header is not "application/json", then aValueError will be raised when trying to parse the response.

request
The request data that stimulated the response.
wsgi_request
The WSGIRequest instance generated by the test handler thatgenerated the response.
status_code
The HTTP status of the response, as an integer. For a full listof defined codes, see the IANA status code registry.
templates
A list of Template instances used to render the final content, inthe order they were rendered. For each template in the list, usetemplate.name to get the template’s file name, if the template wasloaded from a file. (The name is a string such as'admin/index.html'.)

Not using Django templates?

This attribute is only populated when using theDjangoTemplates backend.If you’re using another template engine,template_namemay be a suitable alternative if you only need the name of thetemplate used for rendering.

resolver_match
An instance of ResolverMatch for the response.You can use the func attribute, forexample, to verify the view that served the response:

# my_view here is a function based view
self.assertEqual(response.resolver_match.func, my_view)
 
# class-based views need to be compared by name, as the functions
# generated by as_view() won't be equal
self.assertEqual(response.resolver_match.func.__name__, MyView.as_view().__name__)

If the given URL is not found, accessing this attribute will raise aResolver404 exception.

You can also use dictionary syntax on the response object to query the valueof any settings in the HTTP headers. For example, you could determine thecontent type of a response using response['Content-Type'].

Exceptions

If you point the test client at a view that raises an exception andClient.raise_request_exception is True, that exception will be visiblein the test case. You can then use a standard try … except block orassertRaises() to test for exceptions.

The only exceptions that are not visible to the test client areHttp404,PermissionDenied, SystemExit, andSuspiciousOperation. Django catches theseexceptions internally and converts them into the appropriate HTTP responsecodes. In these cases, you can check response.status_code in your test.

If Client.raise_request_exception is False, the test client will return a500 response as would be returned to a browser. The response has the attributeexc_info to provide information about the unhandledexception.

Persistent state

The test client is stateful. If a response returns a cookie, then that cookiewill be stored in the test client and sent with all subsequent get() andpost() requests.

Expiration policies for these cookies are not followed. If you want a cookieto expire, either delete it manually or create a new Client instance (whichwill effectively delete all cookies).

A test client has two attributes that store persistent state information. Youcan access these properties as part of a test condition.

Client.cookies
A Python SimpleCookie object, containing the currentvalues of all the client cookies. See the documentation of thehttp.cookies module for more.
Client.session
A dictionary-like object containing session information. See thesession documentation for full details.

To modify the session and then save it, it must be stored in a variablefirst (because a new SessionStore is created every time this propertyis accessed):

def test_something(self):
    session = self.client.session
    session['somekey'] = 'test'
    session.save()

Setting the language

When testing applications that support internationalization and localization,you might want to set the language for a test client request. The method fordoing so depends on whether or not theLocaleMiddleware is enabled.

If the middleware is enabled, the language can be set by creating a cookie witha name of LANGUAGE_COOKIE_NAME and a value of the language code:

from django.conf import settings
 
def test_language_using_cookie(self):
    self.client.cookies.load({settings.LANGUAGE_COOKIE_NAME: 'fr'})
    response = self.client.get('/')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

or by including the Accept-Language HTTP header in the request:

def test_language_using_header(self):
    response = self.client.get('/', HTTP_ACCEPT_LANGUAGE='fr')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

More details are in How Django discovers language preference.

If the middleware isn’t enabled, the active language may be set usingtranslation.override():

from django.utils import translation
 
def test_language_using_override(self):
    with translation.override('fr'):
        response = self.client.get('/')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

More details are in Explicitly setting the active language.

Example

The following is a unit test using the test client:

import unittest
from django.test 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 response is 200 OK.
        self.assertEqual(response.status_code, 200)
 
        # Check that the rendered context contains 5 customers.
        self.assertEqual(len(response.context['customers']), 5)

Provided test case classes

Normal Python unit test classes extend a base class ofunittest.TestCase. Django provides a few extensions of this base class:

Hierarchy of Django unit testing classes

You can convert a normal unittest.TestCase to any of the subclasses:change the base class of your test from unittest.TestCase to the subclass.All of the standard Python unit test functionality will be available, and itwill be augmented with some useful additions as described in each sectionbelow.

SimpleTestCase

class SimpleTestCase
A subclass of unittest.TestCase that adds this functionality:
Some useful assertions like:
- Checking that a callable raises a certain exception.
- Checking that a callable triggers a certain warning.
- Testing form field rendering and error treatment.
- Testing HTML responses for the presence/lack of a given fragment.
- Verifying that a template has/hasn't been used to generate a givenresponse content.
- Verifying that two URLs are equal.
- Verifying a HTTP redirect isperformed by the app.
- Robustly testing two HTML fragmentsfor equality/inequality or containment.
- Robustly testing two XML fragmentsfor equality/inequality.
- Robustly testing two JSON fragmentsfor equality.
The ability to run tests with modified settings.
Using the clientClient.If your tests make any database queries, use subclassesTransactionTestCase or TestCase.
SimpleTestCase.databases
New in Django 2.2:

SimpleTestCase disallows database queries by default. Thishelps to avoid executing write queries which will affect other testssince each SimpleTestCase test isn’t run in a transaction. If youaren’t concerned about this problem, you can disable this behavior bysetting the databases class attribute to 'all' on your testclass.

SimpleTestCase.allow_database_queries

Deprecated since version 2.2.

This attribute is deprecated in favor of databases. The previousbehavior of allowdatabasequeries = True can be achieved by settingdatabases = '__all'.

Warning

SimpleTestCase and its subclasses (e.g. TestCase, …) rely onsetUpClass() and tearDownClass() to perform some class-wideinitialization (e.g. overriding settings). If you need to override thosemethods, don’t forget to call the super implementation:

class MyTestCase(TestCase):
 
    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        ...
 
    @classmethod
    def tearDownClass(cls):
        ...
        super().tearDownClass()

Be sure to account for Python’s behavior if an exception is raised duringsetUpClass(). If that happens, neither the tests in the class nortearDownClass() are run. In the case of django.test.TestCase,this will leak the transaction created in super() which results invarious symptoms including a segmentation fault on some platforms (reportedon macOS). If you want to intentionally raise an exception such asunittest.SkipTest in setUpClass(), be sure to do it beforecalling super() to avoid this.

TransactionTestCase

class TransactionTestCase
TransactionTestCase inherits from SimpleTestCase toadd some database-specific features:
Resetting the database to a known state at the beginning of each test toease testing and using the ORM.
Database fixtures.
Test skipping based on database backend features.
The remaining specialized assert* methods.Django’s TestCase class is a more commonly used subclass ofTransactionTestCase that makes use of database transaction facilitiesto speed up the process of resetting the database to a known state at thebeginning of each test. A consequence of this, however, is that some databasebehaviors cannot be tested within a Django TestCase class. For instance,you cannot test that a block of code is executing within a transaction, as isrequired when usingselect_for_update(). In those cases,you should use TransactionTestCase.

TransactionTestCase and TestCase are identical except for the mannerin which the database is reset to a known state and the ability for test codeto test the effects of commit and rollback:

A TransactionTestCase resets the database after the test runs bytruncating all tables. A TransactionTestCase may call commit and rollbackand observe the effects of these calls on the database.
A TestCase, on the other hand, does not truncate tables after a test.Instead, it encloses the test code in a database transaction that is rolledback at the end of the test. This guarantees that the rollback at the end ofthe test restores the database to its initial state.

Warning

TestCase running on a database that does not support rollback (e.g. MySQLwith the MyISAM storage engine), and all instances of TransactionTestCase,will roll back at the end of the test by deleting all data from the testdatabase.

Apps will not see their data reloaded;if you need this functionality (for example, third-party apps should enablethis) you can set serialized_rollback = True inside theTestCase body.

TestCase

class TestCase
This is the most common class to use for writing tests in Django. It inheritsfrom TransactionTestCase (and by extension SimpleTestCase).If your Django application doesn’t use a database, use SimpleTestCase.

The class:

Wraps the tests within two nested atomic()blocks: one for the whole class and one for each test. Therefore, if you wantto test some specific database transaction behavior, useTransactionTestCase.
Checks deferrable database constraints at the end of each test.It also provides an additional method:
classmethod TestCase.setUpTestData()
The class-level atomic block described above allows the creation ofinitial data at the class level, once for the whole TestCase. Thistechnique allows for faster tests as compared to using setUp().

For example:

from django.test import TestCase
 
class MyTests(TestCase):
    @classmethod
    def setUpTestData(cls):
        # Set up data for the whole TestCase
        cls.foo = Foo.objects.create(bar="Test")
        ...
 
    def test1(self):
        # Some test using self.foo
        ...
 
    def test2(self):
        # Some other test using self.foo
        ...

Note that if the tests are run on a database with no transaction support(for instance, MySQL with the MyISAM engine), setUpTestData() will becalled before each test, negating the speed benefits.

Be careful not to modify any objects created in setUpTestData() inyour test methods. Modifications to in-memory objects from setup work doneat the class level will persist between test methods. If you do need tomodify them, you could reload them in the setUp() method withrefresh_from_db(), for example.

LiveServerTestCase

class LiveServerTestCase
LiveServerTestCase does basically the same asTransactionTestCase with one extra feature: it launches alive Django server in the background on setup, and shuts it down on teardown.This allows the use of automated test clients other than theDjango dummy client such as, for example, the Seleniumclient, to execute a series of functional tests inside a browser and simulate areal user’s actions.

The live server listens on localhost and binds to port 0 which uses a freeport assigned by the operating system. The server’s URL can be accessed withself.live_server_url during the tests.

To demonstrate how to use LiveServerTestCase, let’s write a Selenium test.First of all, you need to install the selenium package into your Pythonpath:

/

$ python -m pip install selenium

...\> py -m pip install selenium

Then, add a LiveServerTestCase-based test to your app’s tests module(for example: myapp/tests.py). For this example, we’ll assume you’re usingthe staticfiles app and want to have static files servedduring the execution of your tests similar to what we get at development timewith DEBUG=True, i.e. without having to collect them usingcollectstatic. We’ll usethe StaticLiveServerTestCasesubclass which provides that functionality. Replace it withdjango.test.LiveServerTestCase if you don’t need that.

The code for this test may look as follows:

from django.contrib.staticfiles.testing import StaticLiveServerTestCase
from selenium.webdriver.firefox.webdriver import WebDriver
 
class MySeleniumTests(StaticLiveServerTestCase):
    fixtures = ['user-data.json']
 
    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        cls.selenium = WebDriver()
        cls.selenium.implicitly_wait(10)
 
    @classmethod
    def tearDownClass(cls):
        cls.selenium.quit()
        super().tearDownClass()
 
    def test_login(self):
        self.selenium.get('%s%s' % (self.live_server_url, '/login/'))
        username_input = self.selenium.find_element_by_name("username")
        username_input.send_keys('myuser')
        password_input = self.selenium.find_element_by_name("password")
        password_input.send_keys('secret')
        self.selenium.find_element_by_xpath('//input[@value="Log in"]').click()

Finally, you may run the test as follows:

/

$ ./manage.py test myapp.tests.MySeleniumTests.test_login

...\> manage.py test myapp.tests.MySeleniumTests.test_login

This example will automatically open Firefox then go to the login page, enterthe credentials and press the “Log in” button. Selenium offers other drivers incase you do not have Firefox installed or wish to use another browser. Theexample above is just a tiny fraction of what the Selenium client can do; checkout the full reference for more details.

Note

When using an in-memory SQLite database to run the tests, the same databaseconnection will be shared by two threads in parallel: the thread in whichthe live server is run and the thread in which the test case is run. It’simportant to prevent simultaneous database queries via this sharedconnection by the two threads, as that may sometimes randomly cause thetests to fail. So you need to ensure that the two threads don’t access thedatabase at the same time. In particular, this means that in some cases(for example, just after clicking a link or submitting a form), you mightneed to check that a response is received by Selenium and that the nextpage is loaded before proceeding with further test execution.Do this, for example, by making Selenium wait until the <body> HTML tagis found in the response (requires Selenium > 2.13):

def test_login(self):
    from selenium.webdriver.support.wait import WebDriverWait
    timeout = 2
    ...
    self.selenium.find_element_by_xpath('//input[@value="Log in"]').click()
    # Wait until the response is received
    WebDriverWait(self.selenium, timeout).until(
        lambda driver: driver.find_element_by_tag_name('body'))

The tricky thing here is that there’s really no such thing as a “page load,”especially in modern Web apps that generate HTML dynamically after theserver generates the initial document. So, checking for the presence of<body> in the response might not necessarily be appropriate for all usecases. Please refer to the Selenium FAQ and Selenium documentationfor more information.

Test cases features

Default test client

SimpleTestCase.client
Every test case in a django.test.*TestCase instance has access to aninstance of a Django test client. This client can be accessed asself.client. This client is recreated for each test, so you don’t have toworry about state (such as cookies) carrying over from one test to another.

This means, instead of instantiating a Client in each test:

import unittest
from django.test import Client
 
class SimpleTest(unittest.TestCase):
    def test_details(self):
        client = Client()
        response = client.get('/customer/details/')
        self.assertEqual(response.status_code, 200)
 
    def test_index(self):
        client = Client()
        response = client.get('/customer/index/')
        self.assertEqual(response.status_code, 200)

…you can refer to self.client, like so:

from django.test import TestCase
 
class SimpleTest(TestCase):
    def test_details(self):
        response = self.client.get('/customer/details/')
        self.assertEqual(response.status_code, 200)
 
    def test_index(self):
        response = self.client.get('/customer/index/')
        self.assertEqual(response.status_code, 200)

Customizing the test client

SimpleTestCase.client_class
If you want to use a different Client class (for example, a subclasswith customized behavior), use the client_class classattribute:

from django.test import Client, TestCase
 
class MyTestClient(Client):
    # Specialized methods for your environment
    ...
 
class MyTest(TestCase):
    client_class = MyTestClient
 
    def test_my_stuff(self):
        # Here self.client is an instance of MyTestClient...
        call_some_test_code()

Fixture loading

TransactionTestCase.fixtures
A test case for a database-backed website isn’t much use if there isn’t anydata in the database. Tests are more readable and it’s more maintainable tocreate objects using the ORM, for example in TestCase.setUpTestData(),however, you can also use fixtures.

A fixture is a collection of data that Django knows how to import into adatabase. For example, if your site has user accounts, you might set up afixture of fake user accounts in order to populate your database during tests.

The most straightforward way of creating a fixture is to use themanage.py dumpdata command. This assumes youalready have some data in your database. See the dumpdatadocumentation for more details.

Once you’ve created a fixture and placed it in a fixtures directory in oneof your INSTALLED_APPS, you can use it in your unit tests byspecifying a fixtures class attribute on your django.test.TestCasesubclass:

from django.test import TestCase
from myapp.models import Animal
 
class AnimalTestCase(TestCase):
    fixtures = ['mammals.json', 'birds']
 
    def setUp(self):
        # Test definitions as before.
        call_setup_methods()
 
    def test_fluffy_animals(self):
        # A test that uses the fixtures.
        call_some_test_code()

Here’s specifically what will happen:

At the start of each test, before setUp() is run, Django will flush thedatabase, returning the database to the state it was in directly aftermigrate was called.
Then, all the named fixtures are installed. In this example, Django willinstall any JSON fixture named mammals, followed by any fixture namedbirds. See the loaddata documentation for moredetails on defining and installing fixtures.For performance reasons, TestCase loads fixtures once for the entiretest class, before setUpTestData(), instead of before eachtest, and it uses transactions to clean the database before each test. In any case,you can be certain that the outcome of a test will not be affected by anothertest or by the order of test execution.

By default, fixtures are only loaded into the default database. If you areusing multiple databases and set TransactionTestCase.databases,fixtures will be loaded into all specified databases.

URLconf configuration

If your application provides views, you may want to include tests that use thetest client to exercise those views. However, an end user is free to deploy theviews in your application at any URL of their choosing. This means that yourtests can’t rely upon the fact that your views will be available at aparticular URL. Decorate your test class or test method with@override_settings(ROOT_URLCONF=…) for URLconf configuration.

Multi-database support

TransactionTestCase.databases
New in Django 2.2:

Django sets up a test database corresponding to every database that isdefined in the DATABASES definition in your settings and referred toby at least one test through databases.

However, a big part of the time taken to run a Django TestCase is consumedby the call to flush that ensures that you have a clean database at thestart of each test run. If you have multiple databases, multiple flushes arerequired (one for each database), which can be a time consuming activity –especially if your tests don’t need to test multi-database activity.

As an optimization, Django only flushes the default database atthe start of each test run. If your setup contains multiple databases,and you have a test that requires every database to be clean, you canuse the databases attribute on the test suite to request extra databasesto be flushed.

For example:

class TestMyViews(TransactionTestCase):
    databases = {'default', 'other'}
 
    def test_index_page_view(self):
        call_some_test_code()

This test case will flush the default and other test databases beforerunning testindexpage_view. You can also use '__all' to specifythat all of the test databases must be flushed.

The databases flag also controls which databases theTransactionTestCase.fixtures are loaded into. By default, fixtures areonly loaded into the default database.

Queries against databases not in databases will give assertion errors toprevent state leaking between tests.

TransactionTestCase.multi_db

Deprecated since version 2.2.

This attribute is deprecated in favor of databases.The previous behavior of multidb = True can be achieved by settingdatabases = '_all'.

TestCase.databases
New in Django 2.2:

By default, only the default database will be wrapped in a transactionduring a TestCase’s execution and attempts to query other databases willresult in assertion errors to prevent state leaking between tests.

Use the databases class attribute on the test class to request transactionwrapping against non-default databases.

For example:

class OtherDBTests(TestCase):
    databases = {'other'}
 
    def test_other_db_query(self):
        ...

This test will only allow queries against the other database. Just like forSimpleTestCase.databases and TransactionTestCase.databases, the'all' constant can be used to specify that the test should allowqueries to all databases.

TestCase.multi_db

Deprecated since version 2.2.

This attribute is deprecated in favor of databases. Theprevious behavior of multidb = True can be achieved by settingdatabases = '_all'.

Overriding settings

Warning

Use the functions below to temporarily alter the value of settings in tests.Don’t manipulate django.conf.settings directly as Django won’t restorethe original values after such manipulations.

SimpleTestCase.settings()
For testing purposes it’s often useful to change a setting temporarily andrevert to the original value after running the testing code. For this use caseDjango provides a standard Python context manager (see PEP 343) calledsettings(), which can be used like this:

from django.test import TestCase
 
class LoginTestCase(TestCase):
 
    def test_login(self):
 
        # First check for the default behavior
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/accounts/login/?next=/sekrit/')
 
        # Then override the LOGIN_URL setting
        with self.settings(LOGIN_URL='/other/login/'):
            response = self.client.get('/sekrit/')
            self.assertRedirects(response, '/other/login/?next=/sekrit/')

This example will override the LOGIN_URL setting for the codein the with block and reset its value to the previous state afterwards.

SimpleTestCase.modify_settings()
It can prove unwieldy to redefine settings that contain a list of values. Inpractice, adding or removing values is often sufficient. Django provides themodify_settings() context manager for easiersettings changes:

from django.test import TestCase
 
class MiddlewareTestCase(TestCase):
 
    def test_cache_middleware(self):
        with self.modify_settings(MIDDLEWARE={
            'append': 'django.middleware.cache.FetchFromCacheMiddleware',
            'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
            'remove': [
                'django.contrib.sessions.middleware.SessionMiddleware',
                'django.contrib.auth.middleware.AuthenticationMiddleware',
                'django.contrib.messages.middleware.MessageMiddleware',
            ],
        }):
            response = self.client.get('/')
            # ...

For each action, you can supply either a list of values or a string. When thevalue already exists in the list, append and prepend have no effect;neither does remove when the value doesn’t exist.

override_settings()
In case you want to override a setting for a test method, Django provides theoverride_settings() decorator (see PEP 318). It’s usedlike this:

from django.test import TestCase, override_settings
 
class LoginTestCase(TestCase):
 
    @override_settings(LOGIN_URL='/other/login/')
    def test_login(self):
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/other/login/?next=/sekrit/')

The decorator can also be applied to TestCase classes:

from django.test import TestCase, override_settings
 
@override_settings(LOGIN_URL='/other/login/')
class LoginTestCase(TestCase):
 
    def test_login(self):
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/other/login/?next=/sekrit/')

modify_settings()
Likewise, Django provides the modify_settings()decorator:

from django.test import TestCase, modify_settings
 
class MiddlewareTestCase(TestCase):
 
    @modify_settings(MIDDLEWARE={
        'append': 'django.middleware.cache.FetchFromCacheMiddleware',
        'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
    })
    def test_cache_middleware(self):
        response = self.client.get('/')
        # ...

The decorator can also be applied to test case classes:

from django.test import TestCase, modify_settings
 
@modify_settings(MIDDLEWARE={
    'append': 'django.middleware.cache.FetchFromCacheMiddleware',
    'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
})
class MiddlewareTestCase(TestCase):
 
    def test_cache_middleware(self):
        response = self.client.get('/')
        # ...

Note

When given a class, these decorators modify the class directly and returnit; they don’t create and return a modified copy of it. So if you try totweak the above examples to assign the return value to a different namethan LoginTestCase or MiddlewareTestCase, you may be surprised tofind that the original test case classes are still equally affected by thedecorator. For a given class, modify_settings() isalways applied after override_settings().

Warning

The settings file contains some settings that are only consulted duringinitialization of Django internals. If you change them withoverride_settings, the setting is changed if you access it via thedjango.conf.settings module, however, Django’s internals access itdifferently. Effectively, using override_settings() ormodify_settings() with these settings is probably notgoing to do what you expect it to do.

We do not recommend altering the DATABASES setting. Alteringthe CACHES setting is possible, but a bit tricky if you areusing internals that make using of caching, likedjango.contrib.sessions. For example, you will have to reinitializethe session backend in a test that uses cached sessions and overridesCACHES.

Finally, avoid aliasing your settings as module-level constants asoverride_settings() won’t work on such values since they areonly evaluated the first time the module is imported.

You can also simulate the absence of a setting by deleting it after settingshave been overridden, like this:

@override_settings()def test_something(self):    del settings.LOGIN_URL    …

When overriding settings, make sure to handle the cases in which your app’scode uses a cache or similar feature that retains state even if the setting ischanged. Django provides the django.test.signals.setting_changedsignal that lets you register callbacks to clean up and otherwise reset statewhen settings are changed.

Django itself uses this signal to reset various data:

Overridden settings	Data reset
USE_TZ, TIME_ZONE	Databases timezone
TEMPLATES	Template engines
SERIALIZATION_MODULES	Serializers cache
LOCALE_PATHS, LANGUAGE_CODE	Default translation and loaded translations
MEDIA_ROOT, DEFAULT_FILE_STORAGE	Default file storage

Emptying the test outbox

If you use any of Django’s custom TestCase classes, the test runner willclear the contents of the test email outbox at the start of each test case.

For more detail on email services during tests, see Email services below.

Assertions

As Python’s normal unittest.TestCase class implements assertion methodssuch as assertTrue() andassertEqual(), Django’s custom TestCase classprovides a number of custom assertion methods that are useful for testing Webapplications:

The failure messages given by most of these assertion methods can be customizedwith the msg_prefix argument. This string will be prefixed to any failuremessage generated by the assertion. This allows you to provide additionaldetails that may help you to identify the location and cause of a failure inyour test suite.

SimpleTestCase.assertRaisesMessage(expected_exception, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertRaisesMessage(expected_exception, expected_message)
Asserts that execution of callable raises expected_exception andthat expected_message is found in the exception’s message. Any otheroutcome is reported as a failure. It’s a simpler version ofunittest.TestCase.assertRaisesRegex() with the difference thatexpected_message isn’t treated as a regular expression.

If only the expected_exception and expected_message parameters aregiven, returns a context manager so that the code being tested can bewritten inline rather than as a function:

with self.assertRaisesMessage(ValueError, 'invalid literal for int()'):
    int('a')

SimpleTestCase.assertWarnsMessage(expected_warning, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertWarnsMessage(expected_warning, expected_message)
Analogous to SimpleTestCase.assertRaisesMessage() but forassertWarnsRegex() instead ofassertRaisesRegex().
SimpleTestCase.assertFieldOutput(fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value='')
Asserts that a form field behaves correctly with various inputs.

Parameters:

fieldclass – the class of the field to be tested.
valid – a dictionary mapping valid inputs to their expected cleanedvalues.
invalid – a dictionary mapping invalid inputs to one or more raisederror messages.
field_args – the args passed to instantiate the field.
field_kwargs – the kwargs passed to instantiate the field.
empty_value – the expected clean output for inputs in empty_values.

For example, the following code tests that an EmailField acceptsa@a.com as a valid email address, but rejects aaa with a reasonableerror message:

self.assertFieldOutput(EmailField, {'a@a.com': 'a@a.com'}, {'aaa': ['Enter a valid email address.']})

SimpleTestCase.assertFormError(response, form, field, errors, msg_prefix='')
Asserts that a field on a form raises the provided list of errors whenrendered on the form.

form is the name the Form instance was given in the templatecontext.

field is the name of the field on the form to check. If fieldhas a value of None, non-field errors (errors you can access viaform.non_field_errors()) willbe checked.

errors is an error string, or a list of error strings, that areexpected as a result of form validation.

SimpleTestCase.assertFormsetError(response, formset, form_index, field, errors, msg_prefix='')
Asserts that the formset raises the provided list of errors whenrendered.

formset is the name the Formset instance was given in the templatecontext.

form_index is the number of the form within the Formset. Ifform_index has a value of None, non-form errors (errors you canaccess via formset.non_form_errors()) will be checked.

field is the name of the field on the form to check. If fieldhas a value of None, non-field errors (errors you can access viaform.non_field_errors()) willbe checked.

errors is an error string, or a list of error strings, that areexpected as a result of form validation.

SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)
Asserts that a Response instance produced the given status_code andthat text appears in the content of the response. If count isprovided, text must occur exactly count times in the response.

Set html to True to handle text as HTML. The comparison withthe response content will be based on HTML semantics instead ofcharacter-by-character equality. Whitespace is ignored in most cases,attribute ordering is not significant. SeeassertHTMLEqual() for more details.

SimpleTestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)
Asserts that a Response instance produced the given statuscode andthat text does _not appear in the content of the response.

SimpleTestCase.assertTemplateUsed(response, template_name, msg_prefix='', count=None)
Asserts that the template with the given name was used in rendering theresponse.

The name is a string such as 'admin/index.html'.

The count argument is an integer indicating the number of times thetemplate should be rendered. Default is None, meaning that the templateshould be rendered one or more times.

You can use this as a context manager, like this:

with self.assertTemplateUsed('index.html'):
    render_to_string('index.html')
with self.assertTemplateUsed(template_name='index.html'):
    render_to_string('index.html')

SimpleTestCase.assertTemplateNotUsed(response, template_name, msg_prefix='')
Asserts that the template with the given name was not used in renderingthe response.

You can use this as a context manager in the same way asassertTemplateUsed().

SimpleTestCase.assertURLEqual(url1, url2, msg_prefix='')
New in Django 2.2:

Asserts that two URLs are the same, ignoring the order of query stringparameters except for parameters with the same name. For example,/path/?x=1&y=2 is equal to /path/?y=2&x=1, but/path/?a=1&a=2 isn’t equal to /path/?a=2&a=1.

SimpleTestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200, msg_prefix='', fetch_redirect_response=True)
Asserts that the response returned a status_code redirect status,redirected to expected_url (including any GET data), and that thefinal page was received with target_status_code.

If your request used the follow argument, the expected_url andtarget_status_code will be the url and status code for the finalpoint of the redirect chain.

If fetch_redirect_response is False, the final page won’t beloaded. Since the test client can’t fetch external URLs, this isparticularly useful if expected_url isn’t part of your Django app.

Scheme is handled correctly when making comparisons between two URLs. Ifthere isn’t any scheme specified in the location where we are redirected to,the original request’s scheme is used. If present, the scheme inexpected_url is the one used to make the comparisons to.

SimpleTestCase.assertHTMLEqual(html1, html2, msg=None)
Asserts that the strings html1 and html2 are equal. The comparisonis based on HTML semantics. The comparison takes following things intoaccount:
- Whitespace before and after HTML tags is ignored.
- All types of whitespace are considered equivalent.
- All open tags are closed implicitly, e.g. when a surrounding tag isclosed or the HTML document ends.
- Empty tags are equivalent to their self-closing version.
- The ordering of attributes of an HTML element is not significant.
- Attributes without an argument are equal to attributes that equal inname and value (see the examples).
- Text, character references, and entity references that refer to the samecharacter are equivalent.The following examples are valid tests and don’t raise anyAssertionError:

self.assertHTMLEqual(
    '<p>Hello <b>&#x27;world&#x27;!</p>',
    '''<p>
        Hello   <b>&#39;world&#39;! </b>
    </p>'''
)
self.assertHTMLEqual(
    '<input type="checkbox" checked="checked" id="id_accept_terms" />',
    '<input id="id_accept_terms" type="checkbox" checked>'
)

html1 and html2 must be valid HTML. An AssertionError will beraised if one of them cannot be parsed.