djangofrdoc / ref / contrib / gis / testing.txt

Full commit
Testing GeoDjango Apps

.. versionchanged:: 1.2

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.

.. _testing-postgis:



.. note::

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



.. versionchanged:: 1.2

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
:ref:`installation documentation <spatialdb_template>`).

.. setting:: POSTGIS_VERSION


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
:ref:`spatial database template <spatialdb_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)::


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``


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``.

.. _testing-spatialite:


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

    $ wget
    $ unzip

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

    $ python test


.. setting:: SPATIALITE_SQL


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
```` is located).  If you want to use a different location, then
you may add the following to your settings::



.. _geodjango-tests:

GeoDjango Tests

.. versionchanged:: 1.3

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 ````.


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`::

        '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 ```` file in the same
directory as ````, then all Django and GeoDjango tests would
be performed when executing the command::

    $ ./ --settings=postgis