============= Testing tools ============= .. currentmodule:: django.test Django provides a small set of tools that come in handy when writing tests. .. _test-client: The test client =============== The test client is a Python class that acts as a dummy web browser, allowing you to test your views and interact with your Django-powered application programmatically. 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) to page content. * See the chain of redirects (if any) and check the URL and status code at each step. * Test that a given request is rendered by a given Django template, with a template context that contains certain values. Note that the test client is not intended to be a replacement for Selenium_ or other "in-browser" frameworks. Django's test client has a different focus. In short: * Use Django's test client to establish that the correct template is being rendered and that the template is passed the correct context data. * Use :class:`~django.test.RequestFactory` to test view functions directly, bypassing the routing and middleware layers. * Use in-browser frameworks like Selenium_ to test *rendered* HTML and the *behavior* of web pages, namely JavaScript functionality. Django also provides special support for those frameworks; see the section on :class:`~django.test.LiveServerTestCase` for more details. A comprehensive test suite should use a combination of all of these test types. Overview and a quick example ---------------------------- To use the test client, instantiate ``django.test.Client`` and retrieve web 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'>> 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 not powered by your Django project. If you need to retrieve other web pages, use a Python standard library module such as :mod:`urllib`. * To resolve URLs, the test client uses whatever URLconf is pointed-to by your :setting:`ROOT_URLCONF` setting. * Although the above example would work in the Python interactive interpreter, some of the test client's functionality, notably the template-related functionality, is only available *while tests are running*. The reason for this is that Django's test runner performs a bit of black magic in order to determine which template was loaded by a given view. This black magic (essentially a patching of Django's template system in memory) only happens during test running. * By default, the test client will disable any CSRF checks performed by your site. If, for some reason, you *want* the test client to perform CSRF checks, you can create an instance of the test client that enforces CSRF checks. To do this, pass in the ``enforce_csrf_checks`` argument when you construct your client:: >>> 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, raise_request_exception=True, json_encoder=DjangoJSONEncoder, **defaults) It requires no arguments at time of construction. However, you can use keyword arguments to specify some default headers. For example, this will send a ``User-Agent`` HTTP header in each request:: >>> c = Client(HTTP_USER_AGENT='Mozilla/5.0') The values from the ``extra`` keyword arguments passed to :meth:`~django.test.Client.get()`, :meth:`~django.test.Client.post()`, etc. have precedence over the defaults passed to the class constructor. The ``enforce_csrf_checks`` argument can be used to test CSRF protection (see above). The ``raise_request_exception`` argument allows controlling whether or not exceptions raised during the request should also be raised in the test. Defaults to ``True``. The ``json_encoder`` argument allows setting a custom JSON encoder for the JSON serialization that's described in :meth:`post`. Once you have a ``Client`` instance, you can call any of the following methods: .. method:: Client.get(path, data=None, follow=False, secure=False, **extra) Makes a GET request on the provided ``path`` and returns a ``Response`` object, which is documented below. The key-value pairs in the ``data`` dictionary are used to create a GET data 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 specify headers to be sent in the request. For example:: >>> c = Client() >>> c.get('/customers/details/', {'name': 'fred', 'age': 7}, ... HTTP_ACCEPT='application/json') ...will send the HTTP header ``HTTP_ACCEPT`` to the details view, which is a good way to test code paths that use the :meth:`django.http.HttpRequest.accepts()` method. .. admonition:: CGI specification The headers sent via ``**extra`` should follow CGI_ specification. For example, emulating a different "Host" header as sent in the HTTP request from the browser to the server should be passed as ``HTTP_HOST``. .. _CGI: https://www.w3.org/CGI/ If you already have the GET arguments in URL-encoded form, you can use 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 redirects and a ``redirect_chain`` attribute will be set in the response object containing tuples of the intermediate urls and status codes. If you had a URL ``/redirect_me/`` that redirected to ``/next/``, that redirected 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 HTTPS request. .. method:: Client.post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, **extra) Makes a POST request on the provided ``path`` and returns a ``Response`` object, which is documented below. The key-value pairs in the ``data`` dictionary are used to submit POST data. 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 ``content_type`` as :mimetype:`application/json`, the ``data`` is serialized using :func:`json.dumps` if it's a dict, list, or tuple. Serialization is performed with :class:`~django.core.serializers.json.DjangoJSONEncoder` by default, and can be overridden by providing a ``json_encoder`` argument to :class:`Client`. This serialization also happens for :meth:`put`, :meth:`patch`, and :meth:`delete` requests. If you provide any other ``content_type`` (e.g. :mimetype:`text/xml` for an XML payload), the contents of ``data`` are sent as-is in the POST request, using ``content_type`` in the HTTP ``Content-Type`` header. If you don't provide a value for ``content_type``, the values in ``data`` will be transmitted with a content type of :mimetype:`multipart/form-data`. In this case, the key-value pairs in ``data`` will be encoded as a multipart message and used to create the POST data payload. To submit multiple values for a given key -- for example, to specify the selections for a ``', '' ) ``html1`` and ``html2`` must contain HTML. An ``AssertionError`` will be raised if one of them cannot be parsed. Output in case of error can be customized with the ``msg`` argument. .. method:: SimpleTestCase.assertHTMLNotEqual(html1, html2, msg=None) Asserts that the strings ``html1`` and ``html2`` are *not* equal. The comparison is based on HTML semantics. See :meth:`~SimpleTestCase.assertHTMLEqual` for details. ``html1`` and ``html2`` must contain HTML. An ``AssertionError`` will be raised if one of them cannot be parsed. Output in case of error can be customized with the ``msg`` argument. .. method:: SimpleTestCase.assertXMLEqual(xml1, xml2, msg=None) Asserts that the strings ``xml1`` and ``xml2`` are equal. The comparison is based on XML semantics. Similarly to :meth:`~SimpleTestCase.assertHTMLEqual`, the comparison is made on parsed content, hence only semantic differences are considered, not syntax differences. When invalid XML is passed in any parameter, an ``AssertionError`` is always raised, even if both strings are identical. XML declaration, document type, processing instructions, and comments are ignored. Only the root element and its children are compared. Output in case of error can be customized with the ``msg`` argument. .. method:: SimpleTestCase.assertXMLNotEqual(xml1, xml2, msg=None) Asserts that the strings ``xml1`` and ``xml2`` are *not* equal. The comparison is based on XML semantics. See :meth:`~SimpleTestCase.assertXMLEqual` for details. Output in case of error can be customized with the ``msg`` argument. .. method:: SimpleTestCase.assertInHTML(needle, haystack, count=None, msg_prefix='') Asserts that the HTML fragment ``needle`` is contained in the ``haystack`` once. If the ``count`` integer argument is specified, then additionally the number of ``needle`` occurrences will be strictly verified. Whitespace in most cases is ignored, and attribute ordering is not significant. See :meth:`~SimpleTestCase.assertHTMLEqual` for more details. .. method:: SimpleTestCase.assertJSONEqual(raw, expected_data, msg=None) Asserts that the JSON fragments ``raw`` and ``expected_data`` are equal. Usual JSON non-significant whitespace rules apply as the heavyweight is delegated to the :mod:`json` library. Output in case of error can be customized with the ``msg`` argument. .. method:: SimpleTestCase.assertJSONNotEqual(raw, expected_data, msg=None) Asserts that the JSON fragments ``raw`` and ``expected_data`` are *not* equal. See :meth:`~SimpleTestCase.assertJSONEqual` for further details. Output in case of error can be customized with the ``msg`` argument. .. method:: TransactionTestCase.assertQuerysetEqual(qs, values, transform=None, ordered=True, msg=None) Asserts that a queryset ``qs`` matches a particular iterable of values ``values``. If ``transform`` is provided, ``values`` is compared to a list produced by applying ``transform`` to each member of ``qs``. By default, the comparison is also ordering dependent. If ``qs`` doesn't provide an implicit ordering, you can set the ``ordered`` parameter to ``False``, which turns the comparison into a ``collections.Counter`` comparison. If the order is undefined (if the given ``qs`` isn't ordered and the comparison is against more than one ordered value), a ``ValueError`` is raised. Output in case of error can be customized with the ``msg`` argument. .. method:: TransactionTestCase.assertNumQueries(num, func, *args, **kwargs) Asserts that when ``func`` is called with ``*args`` and ``**kwargs`` that ``num`` database queries are executed. If a ``"using"`` key is present in ``kwargs`` it is used as the database alias for which to check the number of queries:: self.assertNumQueries(7, using='non_default_db') If you wish to call a function with a ``using`` parameter you can do it by wrapping the call with a ``lambda`` to add an extra parameter:: self.assertNumQueries(7, lambda: my_function(using=7)) You can also use this as a context manager:: with self.assertNumQueries(2): Person.objects.create(name="Aaron") Person.objects.create(name="Daniel") .. _topics-tagging-tests: Tagging tests ------------- You can tag your tests so you can easily run a particular subset. For example, you might label fast or slow tests:: from django.test import tag class SampleTestCase(TestCase): @tag('fast') def test_fast(self): ... @tag('slow') def test_slow(self): ... @tag('slow', 'core') def test_slow_but_core(self): ... You can also tag a test case:: @tag('slow', 'core') class SampleTestCase(TestCase): ... Subclasses inherit tags from superclasses, and methods inherit tags from their class. Given:: @tag('foo') class SampleTestCaseChild(SampleTestCase): @tag('bar') def test(self): ... ``SampleTestCaseChild.test`` will be labeled with ``'slow'``, ``'core'``, ``'bar'``, and ``'foo'``. Then you can choose which tests to run. For example, to run only fast tests: .. console:: $ ./manage.py test --tag=fast Or to run fast tests and the core one (even though it's slow): .. console:: $ ./manage.py test --tag=fast --tag=core You can also exclude tests by tag. To run core tests if they are not slow: .. console:: $ ./manage.py test --tag=core --exclude-tag=slow :option:`test --exclude-tag` has precedence over :option:`test --tag`, so if a test has two tags and you select one of them and exclude the other, the test won't be run. .. _async-tests: Testing asynchronous code ========================= If you merely want to test the output of your asynchronous views, the standard test client will run them inside their own asynchronous loop without any extra work needed on your part. However, if you want to write fully-asynchronous tests for a Django project, you will need to take several things into account. Firstly, your tests must be ``async def`` methods on the test class (in order to give them an asynchronous context). Django will automatically detect any ``async def`` tests and wrap them so they run in their own event loop. If you are testing from an asynchronous function, you must also use the asynchronous test client. This is available as ``django.test.AsyncClient``, or as ``self.async_client`` on any test. ``AsyncClient`` has the same methods and signatures as the synchronous (normal) test client, with two exceptions: * The ``follow`` parameter is not supported. * Headers passed as ``extra`` keyword arguments should not have the ``HTTP_`` prefix required by the synchronous client (see :meth:`Client.get`). For example, here is how to set an HTTP ``Accept`` header:: >>> c = AsyncClient() >>> c.get( ... '/customers/details/', ... {'name': 'fred', 'age': 7}, ... ACCEPT='application/json' ... ) Using ``AsyncClient`` any method that makes a request must be awaited:: async def test_my_thing(self): response = await self.async_client.get('/some-url/') self.assertEqual(response.status_code, 200) The asynchronous client can also call synchronous views; it runs through Django's :doc:`asynchronous request path `, which supports both. Any view called through the ``AsyncClient`` will get an ``ASGIRequest`` object for its ``request`` rather than the ``WSGIRequest`` that the normal client creates. .. warning:: If you are using test decorators, they must be async-compatible to ensure they work correctly. Django's built-in decorators will behave correctly, but third-party ones may appear to not execute (they will "wrap" the wrong part of the execution flow and not your test). If you need to use these decorators, then you should decorate your test methods with :func:`~asgiref.sync.async_to_sync` *inside* of them instead:: from asgiref.sync import async_to_sync from django.test import TestCase class MyTests(TestCase): @mock.patch(...) @async_to_sync async def test_my_thing(self): ... .. _topics-testing-email: Email services ============== If any of your Django views send email using :doc:`Django's email functionality `, you probably don't want to send email each time you run a test using that view. For this reason, Django's test runner automatically redirects all Django-sent email to a dummy outbox. This lets you test every aspect of sending email -- from the number of messages sent to the contents of each message -- without actually sending the messages. The test runner accomplishes this by transparently replacing the normal email backend with a testing backend. (Don't worry -- this has no effect on any other email senders outside of Django, such as your machine's mail server, if you're running one.) .. currentmodule:: django.core.mail .. data:: django.core.mail.outbox During test running, each outgoing email is saved in ``django.core.mail.outbox``. This is a list of all :class:`~django.core.mail.EmailMessage` instances that have been sent. The ``outbox`` attribute is a special attribute that is created *only* when the ``locmem`` email backend is used. It doesn't normally exist as part of the :mod:`django.core.mail` module and you can't import it directly. The code below shows how to access this attribute correctly. Here's an example test that examines ``django.core.mail.outbox`` for length and contents:: from django.core import mail from django.test import TestCase class EmailTest(TestCase): def test_send_email(self): # Send message. mail.send_mail( 'Subject here', 'Here is the message.', 'from@example.com', ['to@example.com'], fail_silently=False, ) # Test that one message has been sent. self.assertEqual(len(mail.outbox), 1) # Verify that the subject of the first message is correct. self.assertEqual(mail.outbox[0].subject, 'Subject here') As noted :ref:`previously `, the test outbox is emptied at the start of every test in a Django ``*TestCase``. To empty the outbox manually, assign the empty list to ``mail.outbox``:: from django.core import mail # Empty the test outbox mail.outbox = [] .. _topics-testing-management-commands: Management Commands =================== Management commands can be tested with the :func:`~django.core.management.call_command` function. The output can be redirected into a ``StringIO`` instance:: from io import StringIO from django.core.management import call_command from django.test import TestCase class ClosepollTest(TestCase): def test_command_output(self): out = StringIO() call_command('closepoll', stdout=out) self.assertIn('Expected output', out.getvalue()) .. _skipping-tests: Skipping tests ============== .. currentmodule:: django.test The unittest library provides the :func:`@skipIf ` and :func:`@skipUnless ` decorators to allow you to skip tests if you know ahead of time that those tests are going to fail under certain conditions. For example, if your test requires a particular optional library in order to succeed, you could decorate the test case with :func:`@skipIf `. Then, the test runner will report that the test wasn't executed and why, instead of failing the test or omitting the test altogether. To supplement these test skipping behaviors, Django provides two additional skip decorators. Instead of testing a generic boolean, these decorators check the capabilities of the database, and skip the test if the database doesn't support a specific named feature. The decorators use a string identifier to describe database features. This string corresponds to attributes of the database connection features class. See :source:`django.db.backends.base.features.BaseDatabaseFeatures class ` for a full list of database features that can be used as a basis for skipping tests. .. function:: skipIfDBFeature(*feature_name_strings) Skip the decorated test or ``TestCase`` if all of the named database features are supported. For example, the following test will not be executed if the database supports transactions (e.g., it would *not* run under PostgreSQL, but it would under MySQL with MyISAM tables):: class MyTests(TestCase): @skipIfDBFeature('supports_transactions') def test_transaction_behavior(self): # ... conditional test code pass .. function:: skipUnlessDBFeature(*feature_name_strings) Skip the decorated test or ``TestCase`` if any of the named database features are *not* supported. For example, the following test will only be executed if the database supports transactions (e.g., it would run under PostgreSQL, but *not* under MySQL with MyISAM tables):: class MyTests(TestCase): @skipUnlessDBFeature('supports_transactions') def test_transaction_behavior(self): # ... conditional test code pass