summaryrefslogtreecommitdiff
path: root/docs/topics/testing
diff options
context:
space:
mode:
authorCarlton Gibson <carlton.gibson@noumenal.es>2023-02-09 16:48:46 +0100
committerMariusz Felisiak <felisiak.mariusz@gmail.com>2023-02-10 19:19:13 +0100
commit534ac4829764f317cf2fbc4a18354fcc998c1425 (patch)
treec85c1df220ea6c3a87f9820106ba5a06e9ec9394 /docs/topics/testing
parent7bb741d787ba360a9f0d490db92e22e0d28204ed (diff)
Refs #34140 -- Applied rst code-block to non-Python examples.
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews.
Diffstat (limited to 'docs/topics/testing')
-rw-r--r--docs/topics/testing/advanced.txt12
-rw-r--r--docs/topics/testing/overview.txt28
-rw-r--r--docs/topics/testing/tools.txt78
3 files changed, 87 insertions, 31 deletions
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index 07fb881aee..abcd9072c3 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -414,7 +414,9 @@ you may want to use the Django test runner to run your own test suite
and thus benefit from the Django testing infrastructure.
A common practice is a *tests* directory next to the application code, with the
-following structure::
+following structure:
+
+.. code-block:: text
runtests.py
polls/
@@ -853,12 +855,16 @@ the coverage of your tests.
Django can be easily integrated with `coverage.py`_, a tool for measuring code
coverage of Python programs. First, `install coverage.py`_. Next, run the
-following from your project folder containing ``manage.py``::
+following from your project folder containing ``manage.py``:
+
+.. code-block:: shell
coverage run --source='.' manage.py test myapp
This runs your tests and collects coverage data of the executed files in your
-project. You can see a report of this data by typing following command::
+project. You can see a report of this data by typing following command:
+
+.. code-block:: shell
coverage report
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index 394500b892..a9a539993b 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -75,7 +75,9 @@ Running tests
=============
Once you've written tests, run them using the :djadmin:`test` command of
-your project's ``manage.py`` utility::
+your project's ``manage.py`` utility:
+
+.. code-block:: shell
$ ./manage.py test
@@ -85,7 +87,9 @@ any file named ``test*.py`` under the current working directory.
You can specify particular tests to run by supplying any number of "test
labels" to ``./manage.py test``. Each test label can be a full Python dotted
-path to a package, module, ``TestCase`` subclass, or test method. For instance::
+path to a package, module, ``TestCase`` subclass, or test method. For instance:
+
+.. code-block:: shell
# Run all the tests in the animals.tests module
$ ./manage.py test animals.tests
@@ -100,13 +104,17 @@ path to a package, module, ``TestCase`` subclass, or test method. For instance::
$ ./manage.py test animals.tests.AnimalTestCase.test_animals_can_speak
You can also provide a path to a directory to discover tests below that
-directory::
+directory:
+
+.. code-block:: shell
$ ./manage.py test animals/
You can specify a custom filename pattern match using the ``-p`` (or
``--pattern``) option, if your test files are named differently from the
-``test*.py`` pattern::
+``test*.py`` pattern:
+
+.. code-block:: shell
$ ./manage.py test --pattern="tests_*.py"
@@ -288,7 +296,9 @@ Understanding the test output
When you run your tests, you'll see a number of messages as the test runner
prepares itself. You can control the level of detail of these messages with the
-``verbosity`` option on the command line::
+``verbosity`` option on the command line:
+
+.. code-block:: shell
Creating test database...
Creating table myapp_animal
@@ -298,7 +308,9 @@ This tells you that the test runner is creating a test database, as described
in the previous section.
Once the test database has been created, Django will run your tests.
-If everything goes well, you'll see something like this::
+If everything goes well, you'll see something like this:
+
+.. code-block:: shell
----------------------------------------------------------------------
Ran 22 tests in 0.221s
@@ -306,7 +318,9 @@ If everything goes well, you'll see something like this::
OK
If there are test failures, however, you'll see full details about which tests
-failed::
+failed:
+
+.. code-block:: shell
======================================================================
FAIL: test_was_published_recently_with_future_poll (polls.tests.PollMethodTests)
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 82fa4116f9..85652095a8 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -48,7 +48,9 @@ Overview and a quick example
----------------------------
To use the test client, instantiate ``django.test.Client`` and retrieve
-web pages::
+web pages:
+
+.. code-block:: pycon
>>> from django.test import Client
>>> c = Client()
@@ -70,11 +72,15 @@ Note a few important things about how the test client works:
framework. This helps make the unit tests run quickly.
* When retrieving pages, remember to specify the *path* of the URL, not the
- whole domain. For example, this is correct::
+ whole domain. For example, this is correct:
+
+ .. code-block:: pycon
>>> c.get('/login/')
- This is incorrect::
+ This is incorrect:
+
+ .. code-block:: pycon
>>> c.get('https://www.example.com/login/')
@@ -102,7 +108,9 @@ Note a few important things about how the test client works:
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::
+ client:
+
+ .. code-block:: pycon
>>> from django.test import Client
>>> csrf_client = Client(enforce_csrf_checks=True)
@@ -160,17 +168,23 @@ Use the ``django.test.Client`` class to make requests.
object, which is documented below.
The key-value pairs in the ``data`` dictionary are used to create a GET
- data payload. For example::
+ data payload. For example:
+
+ .. code-block:: pycon
>>> c = Client()
>>> c.get('/customers/details/', {'name': 'fred', 'age': 7})
- ...will result in the evaluation of a GET request equivalent to::
+ ...will result in the evaluation of a GET request equivalent to:
+
+ .. code-block:: text
/customers/details/?name=fred&age=7
The ``headers`` parameter can be used to specify headers to be sent in
- the request. For example::
+ the request. For example:
+
+ .. code-block:: pycon
>>> c = Client()
>>> c.get('/customers/details/', {'name': 'fred', 'age': 7},
@@ -182,17 +196,21 @@ Use the ``django.test.Client`` class to make requests.
Arbitrary keyword arguments set WSGI
:pep:`environ variables <3333#environ-variables>`. For example, headers
- to set the script name::
+ 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::
+ the previous GET request could also be posed as:
- >>> c = Client()
- >>> c.get('/customers/details/?name=fred&age=7')
+ .. 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 a data argument,
the data argument will take precedence.
@@ -202,7 +220,9 @@ Use the ``django.test.Client`` class to make requests.
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::
+ redirected to ``/final/``, this is what you'd see:
+
+ .. code-block:: pycon
>>> response = c.get('/redirect_me/', follow=True)
>>> response.redirect_chain
@@ -221,7 +241,9 @@ Use the ``django.test.Client`` class to make requests.
``Response`` object, which is documented below.
The key-value pairs in the ``data`` dictionary are used to submit POST
- data. For example::
+ data. For example:
+
+ .. code-block:: pycon
>>> c = Client()
>>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})
@@ -264,7 +286,9 @@ Use the ``django.test.Client`` class to make requests.
provide the file field name as a key, and a file handle to the file you
wish to upload as a value. For example, if your form has fields
``name`` and ``attachment``, the latter a
- :class:`~django.forms.FileField`::
+ :class:`~django.forms.FileField`:
+
+ .. code-block:: pycon
>>> c = Client()
>>> with open('wishlist.doc', 'rb') as fp:
@@ -275,7 +299,9 @@ Use the ``django.test.Client`` class to make requests.
: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::
+ For example:
+
+ .. code-block:: pycon
>>> from io import BytesIO
>>> img = BytesIO(
@@ -300,9 +326,11 @@ Use the ``django.test.Client`` class to make requests.
If the URL you request with a POST contains encoded parameters, these
parameters will be made available in the request.GET data. For example,
- if you were to make the request::
+ if you were to make the request:
+
+ .. code-block:: pycon
- >>> c.post('/login/?visitor=true', {'name': 'fred', 'passwd': 'secret'})
+ >>> c.post('/login/?visitor=true', {'name': 'fred', 'passwd': 'secret'})
... the view handling this request could interrogate request.POST
to retrieve the username and password, and could interrogate request.GET
@@ -419,7 +447,9 @@ Use the ``django.test.Client`` class to make requests.
(which is configured by your :setting:`AUTHENTICATION_BACKENDS`
setting). If you're using the standard authentication backend provided
by Django (``ModelBackend``), ``credentials`` should be the user's
- username and password, provided as keyword arguments::
+ username and password, provided as keyword arguments:
+
+ .. code-block:: pycon
>>> c = Client()
>>> c.login(username='fred', password='secret')
@@ -513,7 +543,9 @@ Specifically, a ``Response`` object has the following attributes:
Regardless of the number of templates used during rendering, you can
retrieve context values using the ``[]`` operator. For example, the
- context variable ``name`` could be retrieved using::
+ context variable ``name`` could be retrieved using:
+
+ .. code-block:: pycon
>>> response = client.get('/foo/')
>>> response.context['name']
@@ -545,7 +577,9 @@ Specifically, a ``Response`` object has the following attributes:
.. method:: json(**kwargs)
The body of the response, parsed as JSON. Extra keyword arguments are
- passed to :func:`json.loads`. For example::
+ passed to :func:`json.loads`. For example:
+
+ .. code-block:: pycon
>>> response = client.get('/foo/')
>>> response.json()['name']
@@ -1945,7 +1979,9 @@ 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::
+ example, here is how to set an HTTP ``Accept`` header:
+
+ .. code-block:: pycon
>>> c = AsyncClient()
>>> c.get(