Ticket #13662: running_tests_docs.diff

README

@@ -37 +37 @@
 
     * Check out http://www.djangoproject.com/community/ for information
       about getting involved.
+
+To run Django's included unit tests:
+
+    * Follow the instructions in the section "Unit tests" in
+      docs/faq/contributing.txt, published online at http://docs.djangoproject.com/en/dev/internals/contributing/#claiming-tickets#unit-tests
+ No newline at end of file

docs/internals/contributing.txt

@@ -874 +874 @@
 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 run the tests with the included minimal ``settings`` module, ``cd`` to the
+Django ``tests/`` directory and type:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=test_sqlite
+
+Using the included ``test_sqlite.py`` allows you to get started running the tests
+against the SQLite database backend without doing anything else on your
+filesystem. However it should be noted that running against other database
+backends is recommended for certain types of test cases.
+
+If you get an ``ImportError: No module named django.contrib`` error, you need to add your distribution of Django to your ``PYTHONPATH`` - see `Pointing Python at the new Django version`_ below.
+
+Using another ``settings`` module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
@@ -892 +913 @@
       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).
 
-As a convenience, a minimal settings file, using two in memory SQLite
-databases, 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.
@@ -927 +934 @@
 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:
 
@@ -955 +992 @@
 .. _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
 ------------