Django documentation

Testing GeoDjango Apps

Changed in Django 1.2: Please, see the release notes

In Django 1.2, the addition of Spatial Backends simplified the process of testing GeoDjango applications. Specifically, testing GeoDjango applications is now the same as Testing Django applications.

Included in this documentation are some additional notes and settings for PostGIS and SpatiaLite users.

Note

Django 1.1 users are still required to use a custom TEST_RUNNER. See the Testing GeoDjango Applications in 1.1 section for more details.

PostGIS

Settings

Note

The settings below have sensible defaults, and shouldn’t require manual setting.

POSTGIS_TEMPLATE

New in Django 1.1: Please, see the release notes
Changed in Django 1.2: Please, see the release notes

This setting may be used to customize the name of the PostGIS template database to use. In Django versions 1.2 and above, it automatically defaults to 'template_postgis' (the same name used in the installation documentation).

Note

Django 1.1 users will still have to define the POSTGIS_TEMPLATE with a value, for example:

POSTGIS_TEMPLATE='template_postgis'

POSTGIS_VERSION

New in Django 1.1: Please, see the release notes

When GeoDjango's spatial backend initializes on PostGIS, it has to perform 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, 5, 2)

Obtaining Sufficient Privileges

Depending on your configuration, this section describes several methods to configure a database user with sufficient privileges to run tests for GeoDjango applications on PostgreSQL. If your spatial database template was created like in the instructions, then your testing database user only needs to have the ability to create databases. In other configurations, 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:

$ createuser --createdb -R -S <user_name>

The -R -S flags indicate that we do not want the user to have the ability to create additional users (roles) or to be a superuser, respectively.

Alternatively, you may alter an existing user's role from the SQL shell (assuming this is done from an existing superuser account):

postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;

Create Database Superuser

This may be done at the time the user is created, for example:

$ createuser --superuser <user_name>

Or you may alter the user's role from the SQL shell (assuming this is done from an existing superuser account):

postgres# ALTER ROLE <user_name> SUPERUSER;

Create Local PostgreSQL Database

  1. Initialize database: initdb -D /path/to/user/db
  2. If there's already a Postgres instance on the machine, it will need to use a different TCP port than 5432. Edit postgresql.conf (in /path/to/user/db) to change the database port (e.g. port = 5433).
  3. Start this database pg_ctl -D /path/to/user/db start

Windows

On Windows platforms the pgAdmin III utility may also be used as a simple way to add superuser privileges to your database user.

By default, the PostGIS installer on Windows includes a template spatial database entitled template_postgis.

SpatiaLite

New in Django 1.1: Please, see the release notes

You will need to download the initialization SQL script for SpatiaLite:

$ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
$ unzip init_spatialite-2.3.zip

If init_spatialite-2.3.sql is in the same path as your project's manage.py, then all you have to do is:

$ python manage.py test

Settings

SPATIALITE_SQL

New in Django 1.1: Please, see the release notes

By default, the GeoDjango test runner looks for the SpatiaLite SQL in the same directory where it was invoked (by default the same directory where manage.py is located). If you want to use a different location, then you may add the following to your settings:

SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'

Testing GeoDjango Applications in 1.1

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 TEST_RUNNER as follows:

TEST_RUNNER='django.contrib.gis.tests.run_tests'

Note

In order to create a spatial database, the USER setting (or 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.

GeoDjango Tests

Changed in Django 1.2.4: Please, see the release notes

GeoDjango's test suite may be run in one of two ways, either by itself or with the rest of Django's Unit tests.

Note

The TEST_RUNNER previously used to execute the GeoDjango test suite,:func:django.contrib.gis.tests.run_gis_tests, was deprecated in favor of the django.contrib.gis.tests.GeoDjangoTestSuiteRunner class.

Run only GeoDjango tests

To run only the tests for GeoDjango, the TEST_RUNNER setting must be changed to use the GeoDjangoTestSuiteRunner:

TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'

Example

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'

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'a_spatial_database',
        'USER': 'db_user'
    }
}

Assuming the above is in a file called postgis.py that is in the the same directory as manage.py of your Django project, then you may run the tests with the following command:

$ python manage.py test --settings=postgis

Run with runtests.py

To have the GeoDjango tests executed when running the Django test suite with runtests.py all of the databases in the settings file must be using one of the spatial database backends.

Warning

Do not change the TEST_RUNNER setting when running the GeoDjango tests with runtests.py.

Example

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 django.contrib.gis:

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'geodjango',
        'USER': 'geodjango',
    },
   'other': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'other',
        'USER': 'geodjango',
   }
}

Assuming the settings above were in a postgis.py file in the same directory as runtests.py, then all Django and GeoDjango tests would be performed when executing the command:

$ ./runtests.py --settings=postgis

Questions/Feedback

Having trouble? We'd like to help!

This document is for an insecure version of Django that is no longer supported. Please upgrade to a newer release!