============= 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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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, *, headers=None, query_params=None, **defaults) A testing HTTP client. Takes several arguments that can customize behavior. ``headers`` allows you to specify default headers that will be sent with every request. For example, to set a ``User-Agent`` header:: client = Client(headers={"user-agent": "curl/7.79.1"}) ``query_params`` allows you to specify the default query string that will be set on every request. Arbitrary keyword arguments in ``**defaults`` set WSGI :pep:`environ variables <3333#environ-variables>`. For example, to set the script name:: client = Client(SCRIPT_NAME="/app/") .. note:: Keyword arguments starting with a ``HTTP_`` prefix are set as headers, but the ``headers`` parameter should be preferred for readability. The values from the ``headers``, ``query_params``, and ``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`. .. versionchanged:: 5.1 The ``query_params`` argument was added. Once you have a ``Client`` instance, you can call any of the following methods: .. method:: Client.get(path, data=None, follow=False, secure=False, *, headers=None, query_params=None, **extra) Makes a GET request on the provided ``path`` and returns a ``Response`` object, which is documented below. The key-value pairs in the ``query_params`` dictionary are used to set query strings. For example: .. code-block:: pycon >>> c = Client() >>> c.get("/customers/details/", query_params={"name": "fred", "age": 7}) ...will result in the evaluation of a GET request equivalent to: .. code-block:: text /customers/details/?name=fred&age=7 It is also possible to pass these parameters into the ``data`` parameter. However, ``query_params`` is preferred as it works for any HTTP method. The ``headers`` parameter can be used to specify headers to be sent in the request. For example: .. code-block:: pycon >>> c = Client() >>> c.get( ... "/customers/details/", ... query_params={"name": "fred", "age": 7}, ... headers={"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. Arbitrary keyword arguments set WSGI :pep:`environ variables <3333#environ-variables>`. For example, headers to set the script name: .. code-block:: pycon >>> c = Client() >>> c.get("/", SCRIPT_NAME="/app/") 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: .. code-block:: pycon >>> c = Client() >>> c.get("/customers/details/?name=fred&age=7") If you provide a URL with both an encoded GET data and either a query_params or data argument these arguments 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: .. code-block:: pycon >>> 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. .. versionchanged:: 5.1 The ``query_params`` argument was added. .. method:: Client.post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, *, headers=None, query_params=None, **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: .. code-block:: pycon >>> c = Client() >>> c.post("/login/", {"name": "fred", "passwd": "secret"}) ...will result in the evaluation of a POST request to this URL: .. code-block:: text /login/ ...with this POST data: .. code-block:: text 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. .. versionchanged:: 5.1 In older versions, error messages didn't contain the ``haystack``. .. method:: SimpleTestCase.assertNotInHTML(needle, haystack, msg_prefix="") .. versionadded:: 5.1 Asserts that the HTML fragment ``needle`` is *not* contained in the ``haystack``. 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 class:: @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. .. class:: AsyncClient(enforce_csrf_checks=False, raise_request_exception=True, *, headers=None, query_params=None, **defaults) ``AsyncClient`` has the same methods and signatures as the synchronous (normal) test client, with the following exceptions: * In the initialization, arbitrary keyword arguments in ``defaults`` are added directly into the ASGI scope. * 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: .. code-block:: pycon >>> c = AsyncClient() >>> c.get("/customers/details/", {"name": "fred", "age": 7}, ACCEPT="application/json") .. versionchanged:: 5.0 Support for the ``follow`` parameter was added to the ``AsyncClient``. .. versionchanged:: 5.1 The ``query_params`` argument was added. 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", poll_ids=[1], stdout=out) self.assertIn('Successfully closed poll "1"', 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