diff options
| -rw-r--r-- | README | 6 | ||||
| -rw-r--r-- | docs/internals/contributing.txt | 134 |
2 files changed, 82 insertions, 58 deletions
@@ -35,3 +35,9 @@ To contribute to Django: * Check out http://www.djangoproject.com/community/ for information 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 diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index fd0e48b154..4ce6393181 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -827,29 +827,29 @@ discovered, please follow these guidelines: have a reversion policy doesn't relax your responsibility to aim for the highest quality possible. Really: double-check your work before you commit it in the first place! - + * If possible, have the original author revert his/her own commit. - + * Don't revert another author's changes without permission from the original author. - + * If the original author can't be reached (within a reasonable amount of time -- a day or so) and the problem is severe -- crashing bug, major test failures, etc -- then ask for objections on django-dev then revert if there are none. - + * If the problem is small (a feature commit after feature freeze, say), wait it out. - + * If there's a disagreement between the committer and the reverter-to-be then try to work it out on the `django-developers`_ mailing list. If an agreement can't be reached then it should be put to a vote. - + * If the commit introduced a confirmed, disclosed security vulnerability then the commit may be reverted immediately without permission from anyone. - + * The release branch maintainer may back out commits to the release branch without permission if the commit breaks the release branch. @@ -878,14 +878,41 @@ for an explanation of how to write new 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 ./runtests.py --settings=path.to.django.settings -Yes, the unit tests need a settings module, but only for database connection -info. Your :setting:`DATABASES` setting needs to define two databases: +The :setting:`DATABASES` setting in this 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 @@ -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`` database (although it can use the same backend if you want to). -If you're using the SQLite database backend, you need to define -:setting:`ENGINE` for both databases, plus a -: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: +If you're using a backend that isn't SQLite, you will need to provide other +details for each database: * The :setting:`USER` option for each of your databases needs to 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 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 dependencies: @@ -975,19 +1006,6 @@ associated tests will be skipped. .. _cmemcached: http://gijsbert.org/cmemcache/index.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 ------------ @@ -1234,9 +1252,9 @@ voting mechanism above. A proposition will be considered carried by the core tea if: * There are three "+1" votes from members of the core team. - + * There is no "-1" vote from any member of the core team. - + * The BDFLs haven't stepped in and executed their positive or negative veto. @@ -1263,7 +1281,7 @@ Core committers codebase, a solid track record of being polite and helpful on the mailing lists, and a proven desire to dedicate serious time to Django's development. The bar is high for full commit access. - + Partial committers These are people who are "domain experts." They have direct check-in access to the subsystems that fall under their jurisdiction, and they're given a |