Ticket #6298: test_settings.diff

docs/internals/contributing.txt

@@ -768 +768 @@
 Unit tests
 ==========
 
-Django comes with a test suite of its own, in the ``tests`` directory of the
+Django comes with a test suite of its own, in the ``tests/`` directory of the
 Django tarball. 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``)
-    * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
+    * Everything else in core Django code (``tests/regressiontests/``)
+    * Contrib apps (``django/contrib/<contribapp>/tests/``, see below)
 
 We appreciate any and all contributions to the test suite!
 
@@ -792 +792 @@
 
     ./runtests.py --settings=path.to.django.settings
 
-Yes, the unit tests need a settings module, but only for database connection
-info, with the ``DATABASE_ENGINE`` setting.
+If the copy of Django you want to test is not already in your ``PYTHONPATH``,
+you can run the tests as follows:
 
-If you're using the ``sqlite3`` database backend, no further settings are
-needed. A temporary database will be created in memory when running the tests.
+.. code-block:: bash
 
-If you're using another backend:
+    PYTHONPATH=.. ./runtests.py --settings=path.to.django.settings
+    
+By default, the Django test suite does not output informational or status
+messages while it is running the tests.  To see feedback similar to that
+printed when testing a Django project, add ``--verbosity=1`` (or ``-v 1``) to
+the ``runtests.py`` command.
 
-    * Your :setting:`DATABASE_USER` setting needs to specify an existing user account
-      for the database engine.
+The unit tests need a stripped-down settings module that includes the database
+connection settings.  There is an example settings file named
+``test_settings.py.example`` in the ``tests/`` directory that you can copy
+and modify to suite your local configuration.
+
+If you're using the ``sqlite3`` database backend, only the ``DATABASE_ENGINE``
+setting is needed. A temporary database will be created in memory when running
+the tests.
+
+If you're using another backend you will also need:
 
     * The :setting:`DATABASE_NAME` setting must be the name of an existing database to
       which the given user has permission to connect. The unit tests will not
@@ -810 +822 @@
       deleted when the tests are finished. This means your user account needs
       permission to execute ``CREATE DATABASE``.
 
+    * Unless your database supports ident authentication (and you have it
+      enabled), your :setting:`DATABASE_USER` setting needs to specify an
+      existing user account for the database engine.
+
 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 ``TEST_DATABASE_CHARSET`` in your settings
 file.
 
+The different databases that Django supports behave differently in certain
+situations, so it is recommended to run the test suite against as many
+database backends as possible.  You may want to create a separate settings
+file for each of the backends you test against.
+
+Test suite dependencies
+~~~~~~~~~~~~~~~~~~~~~~~
+
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
 

new file tests/test_settings.py.example

@@ +1 @@
+# This is an example test settings file for use with the Django test suite.
+#
+# To use it, make a copy of this file without the '.example' suffix and fill
+# in the necessary database settings below.  The Django test suite does not
+# require additional configuration in the test settings file.
+#
+# The 'sqlite3' backend requires only the DATABASE_ENGINE setting (an in-
+# memory database will be used).  All other backends will require a
+# DATABASE_NAME and potentially authentication information.  See the
+# following section in the docs for more information:
+#
+# http://docs.djangoproject.com/en/dev/internals/contributing/#unit-tests
+#
+# The different databases that Django supports behave differently in certain
+# situations, so it is recommended to run the test suite against as many
+# database backends as possible.  You may want to create a separate settings
+# file for each of the backends you test against.
+
+DATABASE_ENGINE = ''           # 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
+DATABASE_NAME = ''             # Or path to database file if using sqlite3 (optional).
+DATABASE_USER = ''             # Not used with sqlite3.
+DATABASE_PASSWORD = ''         # Not used with sqlite3.
+DATABASE_HOST = ''             # Set to empty string for localhost. Not used with sqlite3.
+DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.
+