unit-tests.txt

==========
Unit tests
==========

Django comes with a test suite of its own, in the ``tests`` directory of the
code base. It's our policy to make sure all tests pass at all times.

The tests cover:

* Models and the database API (``tests/modeltests``),
* Everything else in core Django code (``tests/regressiontests``),
* :ref:`contrib-apps` (``django/contrib/<app>/tests`` or
  ``tests/regressiontests/<app>_...``).

We appreciate any and all contributions to the test suite!

The Django tests all use the testing infrastructure that ships with Django for
testing applications. See :doc:`Testing Django applications
</topics/testing/overview>` for an explanation of how to write new tests.

.. _running-unit-tests:

Running the unit tests
----------------------

Quickstart
~~~~~~~~~~

Running the tests requires a Django settings module that defines the
databases to use. To make it easy to get started, Django provides a
sample settings module that uses the SQLite database. To run the tests
with this sample ``settings`` module:

.. code-block:: bash

    git clone git@github.com:django/django.git django-repo
    cd django-repo/tests
    PYTHONPATH=..:$PYTHONPATH python ./runtests.py --settings=test_sqlite

.. _running-unit-tests-settings:

Using another ``settings`` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The included settings module allows you to run the test suite using
SQLite. If you want to test behavior using a different database (and
if you're proposing patches for Django, it's a good idea to test
across databases), you may need to define your own settings file.

To run the tests with different settings, ensure that the module is on your
``PYTHONPATH`` and pass the module with ``--settings``.

The :setting:`DATABASES` setting in any test settings module needs to define
two databases:

* A ``default`` database. This database should use the backend that
  you want to use for primary testing

* A database with the alias ``other``. The ``other`` database is
  used to establish that queries can be directed to different
  databases. As a result, this database can use any backend you
  want. It doesn't need to use the same backend as the ``default``
  database (although it can use the same backend if you want to).

If you're using a backend that isn't SQLite, you will need to provide other
details for each database:

* The :setting:`USER` option needs to specify an existing user account
  for the database.

* The :setting:`PASSWORD` option needs to provide the password for
  the :setting:`USER` that has been specified.

* The :setting:`NAME` option must be the name of an existing database to
  which the given user has permission to connect. The unit tests will not
  touch this database; the test runner creates a new database whose name
  is :setting:`NAME` prefixed with ``test_``, and this test database is
  deleted when the tests are finished. This means your user account needs
  permission to execute ``CREATE DATABASE``.

You will also need to ensure that your database uses UTF-8 as the default
character set. If your database server doesn't use UTF-8 as a default charset,
you will need to include a value for :setting:`TEST_CHARSET` in the settings
dictionary for the applicable database.

Running only some of the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django's entire test suite takes a while to run, and running every single test
could be redundant if, say, you just added a test to Django that you want to
run quickly without running everything else. You can run a subset of the unit
tests by appending the names of the test modules to ``runtests.py`` on the
command line.

For example, if you'd like to run tests only for generic relations and
internationalization, type:

.. code-block:: bash

    ./runtests.py --settings=path.to.settings generic_relations i18n

How do you find out the names of individual tests? Look in
``tests/modeltests`` and ``tests/regressiontests`` — each directory name
there is the name of a test. Contrib app names are also valid test names.

If you just want to run a particular class of tests, you can specify a list of
paths to individual test classes. For example, to run the ``TranslationTests``
of the ``i18n`` module, type:

.. code-block:: bash

    ./runtests.py --settings=path.to.settings i18n.TranslationTests

Going beyond that, you can specify an individual test method like this:

.. code-block:: bash

    ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects

Running the Selenium tests
~~~~~~~~~~~~~~~~~~~~~~~~~~

Some admin tests require Selenium 2, Firefox and Python >= 2.6 to work via a
real Web browser. To allow those tests to run and not be skipped, you must
install the selenium_ package (version > 2.13) into your Python path.

Then, run the tests normally, for example:

.. code-block:: bash

    ./runtests.py --settings=test_sqlite admin_inlines

.. _running-unit-tests-dependencies:

Running all the tests
~~~~~~~~~~~~~~~~~~~~~

If you want to run the full suite of tests, you'll need to install a number of
dependencies:

*  numpy_
*  PIL_
*  py-bcrypt_
*  PyYAML_
*  Markdown_
*  Textile_
*  Docutils_
*  pytz_
*  setuptools_
*  memcached_, plus a :ref:`supported Python binding <memcached>`
*  gettext_ (:ref:`gettext_on_windows`)
*  selenium_

You can find these dependencies in `pip requirements files`_ inside the
``tests/requirements`` directory of the Django source tree and install them
like so::

    pip install -r tests/requirements/py2.txt  # Python 3: py3.txt

You can also install the database adapter(s) of your choice using
``oracle.txt``, ``mysql.txt``, or ``postgres.txt``.

If you want to test the memcached cache backend, you'll also need to define
a :setting:`CACHES` setting that points at your memcached instance.

To run the GeoDjango tests, you will need to :doc:`setup a spatial database
and install the Geospatial libraries</ref/contrib/gis/install/index>`.

Each of these dependencies is optional. If you're missing any of them, the
associated tests will be skipped.

.. _numpy: https://pypi.python.org/pypi/numpy
.. _PIL: https://pypi.python.org/pypi/PIL
.. _py-bcrypt: https://pypi.python.org/pypi/py-bcrypt/
.. _PyYAML: http://pyyaml.org/wiki/PyYAML
.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
.. _Textile: http://pypi.python.org/pypi/textile
.. _docutils: http://pypi.python.org/pypi/docutils/0.4
.. _pytz: https://pypi.python.org/pypi/pytz/
.. _setuptools: http://pypi.python.org/pypi/setuptools/
.. _memcached: http://memcached.org/
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
.. _selenium: http://pypi.python.org/pypi/selenium
.. _pip requirements files: http://www.pip-installer.org/en/latest/requirements.html

Code coverage
~~~~~~~~~~~~~

Contributors are encouraged to run coverage on the test suite to identify areas
that need additional tests. The coverage tool installation and use is described
in :ref:`testing code coverage<topics-testing-code-coverage>`.

To run coverage on the Django test suite using the standard test settings::

    coverage run ./runtests.py --settings=test_sqlite

After running coverage, generate the html report by running::

    coverage html

When running coverage for the Django tests, the included ``.coveragerc``
settings file  defines ``coverage_html`` as the output directory for the report
and also excludes several directories not relevant to the results
(test code or external code included in Django).

.. _contrib-apps:

Contrib apps
------------

Tests for contrib apps go in their respective directories under
``django/contrib``, in a ``tests.py`` file. You can split the tests over
multiple modules by using a ``tests`` directory in the normal Python way.

For the tests to be found, a ``models.py`` file must exist, even if it's empty.
If you have URLs that need to be mapped, put them in ``tests/urls.py``.

To run tests for just one contrib app (e.g. ``markup``), use the same
method as above::

    ./runtests.py --settings=settings markup