python/lib/django_1_4/docs/internals/contributing/writing-code/unit-tests.txt

   1 ==========
   2 Unit tests
   3 ==========
   4
   5 Django comes with a test suite of its own, in the ``tests`` directory of the
   6 code base. It's our policy to make sure all tests pass at all times.
   7
   8 The tests cover:
   9
  10 * Models and the database API (``tests/modeltests``),
  11 * Everything else in core Django code (``tests/regressiontests``),
  12 * :ref:`contrib-apps` (``django/contrib/<app>/tests``).
  13
  14 We appreciate any and all contributions to the test suite!
  15
  16 The Django tests all use the testing infrastructure that ships with Django for
  17 testing applications. See :doc:`Testing Django applications </topics/testing>`
  18 for an explanation of how to write new tests.
  19
  20 .. _running-unit-tests:
  21
  22 Running the unit tests
  23 ----------------------
  24
  25 Quickstart
  26 ~~~~~~~~~~
  27
  28 Running the tests requires a Django settings module that defines the
  29 databases to use. To make it easy to get started, Django provides a
  30 sample settings module that uses the SQLite database. To run the tests
  31 with this sample ``settings`` module, ``cd`` into the Django
  32 ``tests/`` directory and run:
  33
  34 .. code-block:: bash
  35
  36     ./runtests.py --settings=test_sqlite
  37
  38 If you get an ``ImportError: No module named django.contrib`` error,
  39 you need to add your install of Django to your ``PYTHONPATH``. For
  40 more details on how to do this, read
  41 :ref:`pointing-python-at-the-new-django-version`.
  42
  43 Using another ``settings`` module
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  45
  46 The included settings module allows you to run the test suite using
  47 SQLite. If you want to test behavior using a different database (and
  48 if you're proposing patches for Django, it's a good idea to test
  49 across databases), you may need to define your own settings file.
  50
  51 To run the tests with different settings, ``cd`` to the ``tests/`` directory
  52 and type:
  53
  54 .. code-block:: bash
  55
  56     ./runtests.py --settings=path.to.django.settings
  57
  58 The :setting:`DATABASES` setting in this test settings module needs to define
  59 two databases:
  60
  61 * A ``default`` database. This database should use the backend that
  62   you want to use for primary testing
  63
  64 * A database with the alias ``other``. The ``other`` database is
  65   used to establish that queries can be directed to different
  66   databases. As a result, this database can use any backend you
  67   want. It doesn't need to use the same backend as the ``default``
  68   database (although it can use the same backend if you want to).
  69
  70 If you're using a backend that isn't SQLite, you will need to provide other
  71 details for each database:
  72
  73 * The :setting:`USER` option for each of your databases needs to
  74   specify an existing user account for the database.
  75
  76 * The :setting:`PASSWORD` option needs to provide the password for
  77   the :setting:`USER` that has been specified.
  78
  79 * The :setting:`NAME` option must be the name of an existing database to
  80   which the given user has permission to connect. The unit tests will not
  81   touch this database; the test runner creates a new database whose name
  82   is :setting:`NAME` prefixed with ``test_``, and this test database is
  83   deleted when the tests are finished. This means your user account needs
  84   permission to execute ``CREATE DATABASE``.
  85
  86 You will also need to ensure that your database uses UTF-8 as the default
  87 character set. If your database server doesn't use UTF-8 as a default charset,
  88 you will need to include a value for :setting:`TEST_CHARSET` in the settings
  89 dictionary for the applicable database.
  90
  91 Running only some of the tests
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93
  94 Django's entire test suite takes a while to run, and running every single test
  95 could be redundant if, say, you just added a test to Django that you want to
  96 run quickly without running everything else. You can run a subset of the unit
  97 tests by appending the names of the test modules to ``runtests.py`` on the
  98 command line.
  99
 100 For example, if you'd like to run tests only for generic relations and
 101 internationalization, type:
 102
 103 .. code-block:: bash
 104
 105     ./runtests.py --settings=path.to.settings generic_relations i18n
 106
 107 How do you find out the names of individual tests? Look in
 108 ``tests/modeltests`` and ``tests/regressiontests`` — each directory name
 109 there is the name of a test. Contrib app names are also valid test names.
 110
 111 If you just want to run a particular class of tests, you can specify a list of
 112 paths to individual test classes. For example, to run the ``TranslationTests``
 113 of the ``i18n`` module, type:
 114
 115 .. code-block:: bash
 116
 117     ./runtests.py --settings=path.to.settings i18n.TranslationTests
 118
 119 Going beyond that, you can specify an individual test method like this:
 120
 121 .. code-block:: bash
 122
 123     ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
 124
 125 Running the Selenium tests
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 Some admin tests require Selenium 2, Firefox and Python >= 2.6 to work via a
 129 real Web browser. To allow those tests to run and not be skipped, you must
 130 install the selenium_ package (version > 2.13) into your Python path.
 131
 132 Then, run the tests normally, for example:
 133
 134 .. code-block:: bash
 135
 136     ./runtests.py --settings=test_sqlite admin_inlines
 137
 138 Running all the tests
 139 ~~~~~~~~~~~~~~~~~~~~~
 140
 141 If you want to run the full suite of tests, you'll need to install a number of
 142 dependencies:
 143
 144 *  PyYAML_
 145 *  Markdown_
 146 *  Textile_
 147 *  Docutils_
 148 *  setuptools_
 149 *  memcached_, plus a :ref:`supported Python binding <memcached>`
 150 *  gettext_ (:ref:`gettext_on_windows`)
 151 *  selenium_ (if also using Python >= 2.6)
 152
 153 If you want to test the memcached cache backend, you'll also need to define
 154 a :setting:`CACHES` setting that points at your memcached instance.
 155
 156 Each of these dependencies is optional. If you're missing any of them, the
 157 associated tests will be skipped.
 158
 159 .. _PyYAML: http://pyyaml.org/wiki/PyYAML
 160 .. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
 161 .. _Textile: http://pypi.python.org/pypi/textile
 162 .. _docutils: http://pypi.python.org/pypi/docutils/0.4
 163 .. _setuptools: http://pypi.python.org/pypi/setuptools/
 164 .. _memcached: http://memcached.org/
 165 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
 166 .. _selenium: http://pypi.python.org/pypi/selenium
 167
 168 Code coverage
 169 ~~~~~~~~~~~~~
 170
 171 Contributors are encouraged to run coverage on the test suite to identify areas
 172 that need additional tests. The coverage tool installation and use is described
 173 in :ref:`testing code coverage<topics-testing-code-coverage>`.
 174
 175 To run coverage on the Django test suite using the standard test settings::
 176
 177     coverage run ./runtests.py --settings=test_sqlite
 178
 179 After running coverage, generate the html report by running::
 180
 181     coverage html
 182
 183 When running coverage for the Django tests, the included ``.coveragerc``
 184 settings file  defines ``coverage_html`` as the output directory for the report
 185 and also excludes several directories not relevant to the results
 186 (test code or external code included in Django).
 187
 188 .. _contrib-apps:
 189
 190 Contrib apps
 191 ------------
 192
 193 Tests for contrib apps go in their respective directories under
 194 ``django/contrib``, in a ``tests.py`` file. You can split the tests over
 195 multiple modules by using a ``tests`` directory in the normal Python way.
 196
 197 For the tests to be found, a ``models.py`` file must exist, even if it's empty.
 198 If you have URLs that need to be mapped, put them in ``tests/urls.py``.
 199
 200 To run tests for just one contrib app (e.g. ``markup``), use the same
 201 method as above::
 202
 203     ./runtests.py --settings=settings markup