[1.2.X] Fixed #13662 -- Added an entry in the README to direct people to the instructions for running the test suite, and cleaned up that section of the docs. Thanks to mir for the report, and to cogat and gg for the draft text.

Backport of r15342 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15345 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Russell Keith-Magee 2011-01-27 03:52:44 +00:00
parent d073d30e45
commit 8ab768f935
2 changed files with 82 additions and 58 deletions

6
README
View File

@ -35,3 +35,9 @@ To contribute to Django:
* Check out http://www.djangoproject.com/community/ for information * Check out http://www.djangoproject.com/community/ for information
about getting involved. about getting involved.
To run Django's test suite:
* Follow the instructions in the "Unit tests" section of
docs/internals/contributing.txt, published online at
http://docs.djangoproject.com/en/dev/internals/contributing/#running-the-unit-tests

View File

@ -878,14 +878,41 @@ for an explanation of how to write new tests.
Running the unit tests Running the unit tests
---------------------- ----------------------
To run the tests, ``cd`` to the ``tests/`` directory and type: 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, ``cd`` into the Django
``tests/`` directory and run:
.. code-block:: bash
./runtests.py --settings=test_sqlite
If you get an ``ImportError: No module named django.contrib`` error,
you need to add your install of Django to your ``PYTHONPATH``. For
more details on how to do this, read `Pointing Python at the new
Django version`_ below.
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, ``cd`` to the ``tests/`` directory
and type:
.. code-block:: bash .. code-block:: bash
./runtests.py --settings=path.to.django.settings ./runtests.py --settings=path.to.django.settings
Yes, the unit tests need a settings module, but only for database connection The :setting:`DATABASES` setting in this test settings module needs to define
info. Your :setting:`DATABASES` setting needs to define two databases: two databases:
* A ``default`` database. This database should use the backend that * A ``default`` database. This database should use the backend that
you want to use for primary testing you want to use for primary testing
@ -896,38 +923,8 @@ info. Your :setting:`DATABASES` setting needs to define two databases:
want. It doesn't need to use the same backend as the ``default`` 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). database (although it can use the same backend if you want to).
If you're using the SQLite database backend, you need to define If you're using a backend that isn't SQLite, you will need to provide other
:setting:`ENGINE` for both databases, plus a details for each database:
:setting:`TEST_NAME` for the ``other`` database. The
following is a minimal settings file that can be used to test SQLite::
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3'
},
'other': {
'ENGINE': 'django.db.backends.sqlite3',
'TEST_NAME': 'other_db'
}
}
As a convenience, this settings file is included in your Django
distribution. It is called ``test_sqlite``, and is included in
the ``tests`` directory. This allows you to get started running
the tests against the sqlite database without doing anything on
your filesystem. However it should be noted that running against
other database backends is recommended for certain types of test
cases.
To run the tests with this included settings file, ``cd``
to the ``tests/`` directory and type:
.. code-block:: bash
./runtests.py --settings=test_sqlite
If you're using another backend, you will need to provide other details for
each database:
* The :setting:`USER` option for each of your databases needs to * The :setting:`USER` option for each of your databases needs to
specify an existing user account for the database. specify an existing user account for the database.
@ -947,6 +944,40 @@ character set. If your database server doesn't use UTF-8 as a default charset,
you will need to include a value for ``TEST_CHARSET`` in the settings you will need to include a value for ``TEST_CHARSET`` in the settings
dictionary for the applicable database. dictionary for the applicable database.
Running only some of the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Django's entire test suite takes a few minutes to run. To run a subset of the
unit tests, append the names of the test modules to the ``runtests.py``
command line.
As an example, if you'd like to only run tests for generic relations and
internationalization, type:
.. code-block:: bash
./runtests.py --settings=path.to.settings generic_relations i18n
See the list of directories in ``tests/modeltests`` and
``tests/regressiontests`` for module 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
You can specify an individual test like this:
.. code-block:: bash
./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
Running all the tests
~~~~~~~~~~~~~~~~~~~~~
If you want to run the full suite of tests, you'll need to install a number of If you want to run the full suite of tests, you'll need to install a number of
dependencies: dependencies:
@ -975,19 +1006,6 @@ associated tests will be skipped.
.. _cmemcached: http://gijsbert.org/cmemcache/index.html .. _cmemcached: http://gijsbert.org/cmemcache/index.html
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
To run a subset of the unit tests, append the names of the test modules to the
``runtests.py`` command line. See the list of directories in
``tests/modeltests`` and ``tests/regressiontests`` for module names.
As an example, if Django is not in your ``PYTHONPATH``, you placed
``settings.py`` in the ``tests/`` directory, and you'd like to only run tests
for generic relations and internationalization, type:
.. code-block:: bash
PYTHONPATH=`pwd`/..
./runtests.py --settings=settings generic_relations i18n
Contrib apps Contrib apps
------------ ------------