diff options
Diffstat (limited to 'docs/topics/testing')
| -rw-r--r-- | docs/topics/testing/overview.txt | 19 | ||||
| -rw-r--r-- | docs/topics/testing/tools.txt | 109 |
2 files changed, 67 insertions, 61 deletions
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 80e6663f6b..cafd9dd883 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -11,8 +11,8 @@ Writing and running tests reference </topics/testing/tools>`, and the :doc:`advanced testing topics </topics/testing/advanced>`. -This document is split into two primary sections. First, we explain how to write -tests with Django. Then, we explain how to run them. +This document is split into two primary sections. First, we explain how to +write tests with Django. Then, we explain how to run them. Writing tests ============= @@ -187,12 +187,12 @@ test database is created by the user specified by :setting:`USER`, so you'll need to make sure that the given user account has sufficient privileges to create a new database on the system. -For fine-grained control over the character encoding of your test -database, use the :setting:`CHARSET <TEST_CHARSET>` TEST option. If you're using -MySQL, you can also use the :setting:`COLLATION <TEST_COLLATION>` option to -control the particular collation used by the test database. See the -:doc:`settings documentation </ref/settings>` for details of these -and other advanced settings. +For fine-grained control over the character encoding of your test database, use +the :setting:`CHARSET <TEST_CHARSET>` TEST option. If you're using MySQL, you +can also use the :setting:`COLLATION <TEST_COLLATION>` option to control the +particular collation used by the test database. See the :doc:`settings +documentation </ref/settings>` for details of these and other advanced +settings. If using an SQLite in-memory database with SQLite, `shared cache <https://www.sqlite.org/sharedcache.html>`_ is enabled, so you can write tests @@ -212,7 +212,8 @@ with ability to share the database between threads. .. seealso:: - The :ref:`advanced multi-db testing topics <topics-testing-advanced-multidb>`. + The :ref:`advanced multi-db testing topics + <topics-testing-advanced-multidb>`. .. _order-of-tests: diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 7943b3dcac..4c93e762c7 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -301,12 +301,12 @@ Use the ``django.test.Client`` class to make requests. ... c.post("/customers/wishes/", {"name": "fred", "attachment": fp}) ... - You may also provide any file-like object (e.g., :class:`~io.StringIO` or - :class:`~io.BytesIO`) as a file handle. If you're uploading to an + You may also provide any file-like object (e.g., :class:`~io.StringIO` + or :class:`~io.BytesIO`) as a file handle. If you're uploading to an :class:`~django.db.models.ImageField`, the object needs a ``name`` attribute that passes the - :data:`~django.core.validators.validate_image_file_extension` validator. - For example: + :data:`~django.core.validators.validate_image_file_extension` + validator. For example: .. code-block:: pycon @@ -341,8 +341,8 @@ Use the ``django.test.Client`` class to make requests. ... "/login/", {"name": "fred", "passwd": "secret"}, query_params={"visitor": "true"} ... ) - ... the view handling this request could interrogate request.POST - to retrieve the username and password, and could interrogate request.GET + ... the view handling this request could interrogate request.POST to + retrieve the username and password, and could interrogate request.GET to determine if the user was a visitor. If you set ``follow`` to ``True`` the client will follow any redirects @@ -417,10 +417,10 @@ Use the ``django.test.Client`` class to make requests. *Asynchronous version*: ``alogin()`` - If your site uses Django's :doc:`authentication system</topics/auth/index>` - and you deal with logging in users, you can use the test client's - ``login()`` method to simulate the effect of a user logging into the - site. + If your site uses Django's + :doc:`authentication system</topics/auth/index>` and you deal with + logging in users, you can use the test client's ``login()`` method to + simulate the effect of a user logging into the site. After you call this method, the test client will have all the cookies and session data required to pass any login-based tests that may form @@ -493,9 +493,10 @@ Use the ``django.test.Client`` class to make requests. *Asynchronous version*: ``alogout()`` - If your site uses Django's :doc:`authentication system</topics/auth/index>`, - the ``logout()`` method can be used to simulate the effect of a user - logging out of your site. + If your site uses Django's + :doc:`authentication system</topics/auth/index>`, the ``logout()`` + method can be used to simulate the effect of a user logging out of your + site. After you call this method, the test client will have all the cookies and session data cleared to defaults. Subsequent requests will appear @@ -525,11 +526,12 @@ Specifically, a ``Response`` object has the following attributes: .. attribute:: context - The template ``Context`` instance that was used to render the template that - produced the response content. + The template ``Context`` instance that was used to render the template + that produced the response content. - If the rendered page used multiple templates, then ``context`` will be a - list of ``Context`` objects, in the order in which they were rendered. + If the rendered page used multiple templates, then ``context`` will be + a list of ``Context`` objects, in the order in which they were + rendered. Regardless of the number of templates used during rendering, you can retrieve context values using the ``[]`` operator. For example, the @@ -646,9 +648,9 @@ The only exceptions that are not visible to the test client are exceptions internally and converts them into the appropriate HTTP response codes. In these cases, you can check ``response.status_code`` in your test. -If ``Client.raise_request_exception`` is ``False``, the test client will return a -500 response as would be returned to a browser. The response has the attribute -:attr:`~Response.exc_info` to provide information about the unhandled +If ``Client.raise_request_exception`` is ``False``, the test client will return +a 500 response as would be returned to a browser. The response has the +attribute :attr:`~Response.exc_info` to provide information about the unhandled exception. Persistent state @@ -772,7 +774,8 @@ Provided test case classes ========================== Normal Python unit test classes extend a base class of -:class:`unittest.TestCase`. Django provides a few extensions of this base class: +:class:`unittest.TestCase`. Django provides a few extensions of this base +class: .. _testcase_hierarchy_diagram: @@ -811,12 +814,13 @@ A subclass of :class:`unittest.TestCase` that adds this functionality: * Verifying that two :meth:`URLs <SimpleTestCase.assertURLEqual>` are equal. * Verifying an HTTP :meth:`redirect <SimpleTestCase.assertRedirects>` is performed by the app. - * Robustly testing two :meth:`HTML fragments <SimpleTestCase.assertHTMLEqual>` - for equality/inequality or :meth:`containment <SimpleTestCase.assertInHTML>`. + * Robustly testing two :meth:`HTML fragments + <SimpleTestCase.assertHTMLEqual>` for equality/inequality or + :meth:`containment <SimpleTestCase.assertInHTML>`. * Robustly testing two :meth:`XML fragments <SimpleTestCase.assertXMLEqual>` for equality/inequality. - * Robustly testing two :meth:`JSON fragments <SimpleTestCase.assertJSONEqual>` - for equality. + * Robustly testing two :meth:`JSON fragments + <SimpleTestCase.assertJSONEqual>` for equality. * The ability to run tests with :ref:`modified settings <overriding-settings>`. * Using the :attr:`~SimpleTestCase.client` :class:`~django.test.Client`. @@ -901,9 +905,9 @@ to test the effects of commit and rollback: .. warning:: ``TestCase`` running on a database that does not support rollback (e.g. MySQL - with the MyISAM storage engine), and all instances of ``TransactionTestCase``, - will roll back at the end of the test by deleting all data from the test - database. + with the MyISAM storage engine), and all instances of + ``TransactionTestCase``, will roll back at the end of the test by deleting + all data from the test database. Apps :ref:`will not see their data reloaded <test-case-serialized-rollback>`; if you need this functionality (for example, third-party apps should enable @@ -1105,9 +1109,9 @@ out the `full reference`_ for more details. 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 the - server generates the initial document. So, checking for the presence of + 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 + the server generates the initial document. So, checking for the presence of ``<body>`` in the response might not necessarily be appropriate for all use cases. Please refer to the `Selenium FAQ`_ and `Selenium documentation`_ for more information. @@ -1335,9 +1339,9 @@ 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 restore - the original values after such manipulations. + Use the functions below to temporarily alter the value of settings in + tests. Don't manipulate ``django.conf.settings`` directly as Django won't + restore the original values after such manipulations. .. method:: SimpleTestCase.settings() @@ -1595,8 +1599,8 @@ For more detail on email services during tests, see `Email services`_ below. Assertions ---------- -As Python's normal :class:`unittest.TestCase` class implements assertion methods -such as :meth:`~unittest.TestCase.assertTrue` and +As Python's normal :class:`unittest.TestCase` class implements assertion +methods such as :meth:`~unittest.TestCase.assertTrue` and :meth:`~unittest.TestCase.assertEqual`, Django's custom :class:`TestCase` class provides a number of custom assertion methods that are useful for testing web applications: @@ -1641,7 +1645,8 @@ your test suite. error messages. :param field_args: the args passed to instantiate the field. :param field_kwargs: the kwargs passed to instantiate the field. - :param empty_value: the expected clean output for inputs in ``empty_values``. + :param empty_value: the expected clean output for inputs in + ``empty_values``. For example, the following code tests that an ``EmailField`` accepts ``a@a.com`` as a valid email address, but rejects ``aaa`` with a reasonable @@ -1660,8 +1665,8 @@ your test suite. validated (``assertFormError()`` will automatically call ``full_clean()`` on the form). - ``field`` is the name of the field on the form to check. To check the form's - :meth:`non-field errors <django.forms.Form.non_field_errors>`, use + ``field`` is the name of the field on the form to check. To check the + form's :meth:`non-field errors <django.forms.Form.non_field_errors>`, use ``field=None``. ``errors`` is a list of all the error strings that the field is expected to @@ -1763,8 +1768,8 @@ your test suite. particularly useful if ``expected_url`` isn't part of your Django app. Scheme is handled correctly when making comparisons between two URLs. If - there isn't any scheme specified in the location where we are redirected to, - the original request's scheme is used. If present, the scheme in + there isn't any scheme specified in the location where we are redirected + to, the original request's scheme is used. If present, the scheme in ``expected_url`` is the one used to make the comparisons to. .. method:: SimpleTestCase.assertHTMLEqual(html1, html2, msg=None) @@ -1841,8 +1846,8 @@ your test suite. 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. + 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. @@ -1865,8 +1870,8 @@ your test suite. .. 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. + 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. @@ -1880,10 +1885,10 @@ your test suite. 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. + ``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. @@ -2018,9 +2023,9 @@ 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). + 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:: |