<commit_before>=============
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 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 both 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': '<PASSWORD>'})
    >>> response.status_code
    200
    >>> response = c.get('/customer/details/')
    >>> response.content
    b'<!DOCTYPE html...'

As this example suggests, you can instantiate ``Client`` from within a session
of the Python interactive interpreter.

Note a few important things about how the test client works:

* The test client does *not* require the Web server to be running. In fact,
  it will run just fine with no Web server running at all! That's because
  it avoids the overhead of HTTP and deals directly with the Django
  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::

      >>> 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, json_encoder=DjangoJSONEncoder, **defaults)

    It requires no arguments at time of construction. However, you can use
    keywords 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`` keywords arguments passed to
    :meth:`~django.test.Client.get()`,
    :meth:`~django.test.Client.post()`, etc. have precedence over<commit_msg>[3.2.x] Fixed #32438 -- Fixed typo in docs/topics/testing/tools.txt.<commit_after>=============
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 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 both 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': '<PASSWORD>'})
    >>> response.status_code
    200
    >>> response = c.get('/customer/details/')
    >>> response.content
    b'<!DOCTYPE html...'

As this example suggests, you can instantiate ``Client`` from within a session
of the Python interactive interpreter.

Note a few important things about how the test client works:

* The test client does *not* require the Web server to be running. In fact,
  it will run just fine with no Web server running at all! That's because
  it avoids the overhead of HTTP and deals directly with the Django
  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::

      >>> 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, 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
{'fraction_non_alphanumeric': 0.08927173061863743, 'fraction_numerical': 0.0019017787224521758, 'mean_word_length': 3.707740916271722, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 71, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1182577', 'n_tokens_mistral': 2372, 'n_tokens_neox': 2252, 'n_words': 1201}