mirror of
https://github.com/django/django.git
synced 2025-10-24 14:16:09 +00:00
Refs #36485 -- Rewrapped docs to 79 columns line length.
Lines in the docs files were manually adjusted to conform to the 79 columns limit per line (plus newline), improving readability and consistency across the content.
This commit is contained in:
David Smith
nessita
@@ -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:
|
||||
|
||||
|
||||
@@ -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::
|
||||
|
||||
Reference in New Issue
Block a user