Browse files

Fixed #14439 -- Improved documentation for running the GeoDjango test…

… suite.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent d66ab47 commit b6ab88c34a99e7fc469eb4f6e0df9752f7f3100a @jbronn jbronn committed Dec 22, 2010
Showing with 105 additions and 36 deletions.
  1. +4 −0 docs/internals/contributing.txt
  2. +86 −36 docs/ref/contrib/gis/testing.txt
  3. +15 −0 docs/releases/1.3.txt
@@ -853,6 +853,8 @@ discovered, please follow these guidelines:
* The release branch maintainer may back out commits to the release
branch without permission if the commit breaks the release branch.
+.. _unit-tests:
Unit tests
@@ -871,6 +873,8 @@ The Django tests all use the testing infrastructure that ships with Django for
testing applications. See :doc:`Testing Django applications </topics/testing>`
for an explanation of how to write new tests.
+.. _running-unit-tests:
Running the unit tests
@@ -4,18 +4,13 @@ Testing GeoDjango Apps
.. versionchanged:: 1.2
-In Django 1.2, the addition of :ref:`spatial-backends`
-simplified the process of testing GeoDjango applications. Specifically, testing
-GeoDjango applications is now the same as :doc:`/topics/testing`.
+In Django 1.2, the addition of :ref:`spatial-backends` simplified the
+process of testing GeoDjango applications -- the process is now the
+same as :doc:`/topics/testing`.
Included in this documentation are some additional notes and settings
for :ref:`testing-postgis` and :ref:`testing-spatialite` users.
-.. note::
- Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`.
- See the :ref:`testing-1.1` section for more details.
.. _testing-postgis:
@@ -42,24 +37,21 @@ database to use. In Django versions 1.2 and above, it automatically
defaults to ``'template_postgis'`` (the same name used in the
:ref:`installation documentation <spatialdb_template>`).
-.. note::
- Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE`
- with a value, for example::
- POSTGIS_TEMPLATE='template_postgis'
.. setting:: POSTGIS_VERSION
.. versionadded:: 1.1
When GeoDjango's spatial backend initializes on PostGIS, it has to perform
-a SQL query to determine the version. Setting the version manually
-prevents this query to the database::
+a SQL query to determine the version in order to figure out what
+features are available. Advanced users wishing to prevent this additional
+query may set the version manually using a 3-tuple of integers specifying
+the major, minor, and subminor version numbers for PostGIS. For example,
+to configure for PostGIS 1.5.2 you would use::
- POSTGIS_VERSION=('1.3.6', 1, 3, 6)
+ POSTGIS_VERSION = (1, 5, 2)
Obtaining Sufficient Privileges
@@ -74,6 +66,7 @@ you may be required to use a database superuser.
Create Database User
To make database user with the ability to create databases, use the
following command::
@@ -89,6 +82,7 @@ Alternatively, you may alter an existing user's role from the SQL shell
Create Database Superuser
This may be done at the time the user is created, for example::
$ createuser --superuser <user_name>
@@ -112,6 +106,7 @@ Create Local PostgreSQL Database
On Windows platforms the pgAdmin III utility may also be used as
a simple way to add superuser privileges to your database user.
@@ -142,6 +137,7 @@ Settings
.. versionadded:: 1.1
By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
@@ -153,29 +149,83 @@ you may add the following to your settings::
-.. _testing-1.1:
-Testing GeoDjango Applications in 1.1
+.. _geodjango-tests:
-In Django 1.1, to accommodate the extra steps required to scaffalod a
-spatial database automatically, a test runner customized for GeoDjango
-must be used. To use this runner, configure :setting:`TEST_RUNNER` as follows::
+GeoDjango Tests
- TEST_RUNNER='django.contrib.gis.tests.run_tests'
+.. versionchanged:: 1.3
-.. note::
+GeoDjango's test suite may be run in one of two ways, either by itself or
+with the rest of :ref:`Django's unit tests <unit-tests>`.
+Run only GeoDjango tests
+To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`
+setting must be changed to use the
+ TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
+First, you'll need a bare-bones settings file, like below, that is
+customized with your spatial database name and user::
+ TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
+ 'default': {
+ 'ENGINE': 'django.contrib.gis.db.backends.postgis',
+ 'NAME': 'a_spatial_database',
+ 'USER': 'db_user'
+ }
+ }
+Assuming the above is in a file called ```` that is in the
+the same directory as ```` of your Django project, then
+you may run the tests with the following command::
+ $ python test --settings=postgis
+Run with ````
+To have the GeoDjango tests executed when
+:ref:`running the Django test suite <running-unit-tests>` with ````
+all of the databases in the settings file must be using one of the
+:ref:`spatial database backends <spatial-backends>`.
+.. warning::
+ Do not change the :setting:`TEST_RUNNER` setting
+ when running the GeoDjango tests with ````.
- In order to create a spatial database, the :setting:`USER` setting
- (or :setting:`TEST_USER`, if optionally defined on Oracle) requires
- elevated privileges. When using PostGIS or MySQL, the database user
- must have at least the ability to create databases. When testing on Oracle,
- the user should be a superuser.
+The following is an example bare-bones settings file with spatial backends
+that can be used to run the entire Django test suite, including those
+in :mod:`django.contrib.gis`::
-GeoDjango Test Suite
+ 'default': {
+ 'ENGINE': 'django.contrib.gis.db.backends.postgis',
+ 'NAME': 'geodjango',
+ 'USER': 'geodjango',
+ },
+ 'other': {
+ 'ENGINE': 'django.contrib.gis.db.backends.postgis',
+ 'NAME': 'other',
+ 'USER': 'geodjango',
+ }
+ }
-To run GeoDjango's own internal test suite, configure the
-:setting:`TEST_RUNNER` setting as follows::
+Assuming the settings above were in a ```` file in the same
+directory as ````, then all Django and GeoDjango tests would
+be performed when executing the command::
- TEST_RUNNER='django.contrib.gis.tests.run_gis_tests'
+ $ ./ --settings=postgis
@@ -185,6 +185,13 @@ If you provide a custom auth backend with ``supports_inactive_user`` set to
This is useful for further centralizing the permission handling. See the
:ref:`authentication docs <topics-auth>` for more details.
+The GeoDjango test suite is now included when
+:ref:`running the Django test suite <running-unit-tests>` with ````
+when using :ref:`spatial database backends <spatial-backends>`.
Everything else
@@ -513,3 +520,11 @@ attribute.
Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands
can be used to delete everything. You can also use ALTER TABLE or DROP TABLE
statements manually.
+The :setting:`TEST_RUNNER` previously used to execute the GeoDjango test suite,
+:func:`django.contrib.gis.tests.run_gis_tests`, is deprecated in favor of
+the :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner` class.

0 comments on commit b6ab88c

Please sign in to comment.