1 ======================

     2 Testing GeoDjango Apps

     3 ======================

     4 

     5 .. versionchanged:: 1.2

     6 

     7 In Django 1.2, the addition of :ref:`spatial-backends`

     8 simplified the process of testing GeoDjango applications.  Specifically, testing

     9 GeoDjango applications is now the same as :doc:`/topics/testing`.

    10 

    11 Included in this documentation are some additional notes and settings

    12 for :ref:`testing-postgis` and :ref:`testing-spatialite` users.

    13 

    14 .. note::

    15 

    16     Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`.

    17     See the :ref:`testing-1.1` section for more details.

    18 

    19 .. _testing-postgis:

    20 

    21 PostGIS

    22 =======

    23 

    24 Settings

    25 --------

    26 

    27 .. note::

    28 

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

    30 

    31 .. setting:: POSTGIS_TEMPLATE

    32 

    33 ``POSTGIS_TEMPLATE``

    34 ^^^^^^^^^^^^^^^^^^^^

    35 

    36 .. versionadded:: 1.1

    37 

    38 .. versionchanged:: 1.2

    39 

    40 This setting may be used to customize the name of the PostGIS template

    41 database to use.  In Django versions 1.2 and above, it automatically

    42 defaults to ``'template_postgis'`` (the same name used in the

    43 :ref:`installation documentation <spatialdb_template>`).

    44 

    45 .. note::

    46 

    47     Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE`

    48     with a value, for example::

    49 

    50         POSTGIS_TEMPLATE='template_postgis'

    51 

    52 .. setting:: POSTGIS_VERSION

    53 

    54 ``POSTGIS_VERSION``

    55 ^^^^^^^^^^^^^^^^^^^

    56 

    57 .. versionadded:: 1.1

    58 

    59 When GeoDjango's spatial backend initializes on PostGIS, it has to perform

    60 a SQL query to determine the version in order to figure out what

    61 features are available.  Advanced users wishing to prevent this additional

    62 query may set the version manually using a 3-tuple of integers specifying

    63 the major, minor, and subminor version numbers for PostGIS.  For example,

    64 to configure for PostGIS 1.5.2 you would use::

    65 

    66     POSTGIS_VERSION = (1, 5, 2)

    67 

    68 Obtaining Sufficient Privileges

    69 -------------------------------

    70 

    71 Depending on your configuration, this section describes several methods to

    72 configure a database user with sufficient privileges to run tests for

    73 GeoDjango applications on PostgreSQL.  If your

    74 :ref:`spatial database template <spatialdb_template>`

    75 was created like in the instructions, then your testing database user

    76 only needs to have the ability to create databases.  In other configurations,

    77 you may be required to use a database superuser.

    78 

    79 Create Database User

    80 ^^^^^^^^^^^^^^^^^^^^

    81 

    82 To make database user with the ability to create databases, use the

    83 following command::

    84 

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

    86 

    87 The ``-R -S`` flags indicate that we do not want the user to have the ability

    88 to create additional users (roles) or to be a superuser, respectively.

    89 

    90 Alternatively, you may alter an existing user's role from the SQL shell

    91 (assuming this is done from an existing superuser account)::

    92 

    93     postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;

    94 

    95 Create Database Superuser

    96 ^^^^^^^^^^^^^^^^^^^^^^^^^

    97 

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

    99 

   100     $ createuser --superuser <user_name>

   101 

   102 Or you may alter the user's role from the SQL shell (assuming this

   103 is done from an existing superuser account)::

   104 

   105     postgres# ALTER ROLE <user_name> SUPERUSER;

   106 

   107 

   108 Create Local PostgreSQL Database

   109 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   110 

   111 1. Initialize database: ``initdb -D /path/to/user/db``

   112 

   113 2. If there's already a Postgres instance on the machine, it will need

   114    to use a different TCP port than 5432. Edit ``postgresql.conf`` (in

   115    ``/path/to/user/db``) to change the database port (e.g. ``port = 5433``).

   116 

   117 3. Start this database ``pg_ctl -D /path/to/user/db start``

   118 

   119 Windows

   120 -------

   121 

   122 On Windows platforms the pgAdmin III utility may also be used as

   123 a simple way to add superuser privileges to your database user.

   124 

   125 By default, the PostGIS installer on Windows includes a template

   126 spatial database entitled ``template_postgis``.

   127 

   128 .. _testing-spatialite:

   129 

   130 SpatiaLite

   131 ==========

   132 

   133 .. versionadded:: 1.1

   134 

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

   136 

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

   138     $ unzip init_spatialite-2.3.zip

   139 

   140 If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``,

   141 then all you have to do is::

   142 

   143     $ python manage.py test

   144 

   145 Settings

   146 --------

   147 

   148 .. setting:: SPATIALITE_SQL

   149 

   150 ``SPATIALITE_SQL``

   151 ^^^^^^^^^^^^^^^^^^

   152 

   153 .. versionadded:: 1.1

   154 

   155 By default, the GeoDjango test runner looks for the SpatiaLite SQL in the

   156 same directory where it was invoked (by default the same directory where

   157 ``manage.py`` is located).  If you want to use a different location, then

   158 you may add the following to your settings::

   159 

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

   161 

   162 __ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip

   163 

   164 .. _testing-1.1:

   165 

   166 Testing GeoDjango Applications in 1.1

   167 =====================================

   168 

   169 In Django 1.1, to accommodate the extra steps required to scaffalod a

   170 spatial database automatically, a test runner customized for GeoDjango

   171 must be used.  To use this runner, configure :setting:`TEST_RUNNER` as follows::

   172 

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

   174 

   175 .. note::

   176 

   177     In order to create a spatial database, the :setting:`USER` setting

   178     (or :setting:`TEST_USER`, if optionally defined on Oracle) requires

   179     elevated privileges.  When using PostGIS or MySQL, the database user

   180     must have at least the ability to create databases.  When testing on Oracle,

   181     the user should be a superuser.

   182 

   183 .. _geodjango-tests:

   184 

   185 GeoDjango Tests

   186 ===============

   187 

   188 .. versionchanged:: 1.2.4

   189 

   190 GeoDjango's test suite may be run in one of two ways, either by itself or

   191 with the rest of Django's :ref:`unit-tests`.

   192 

   193 .. note::

   194 

   195     The :setting:`TEST_RUNNER` previously used to execute the GeoDjango

   196     test suite,:func:`django.contrib.gis.tests.run_gis_tests`, was deprecated

   197     in favor of the :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`

   198     class.

   199 

   200 Run only GeoDjango tests

   201 ------------------------

   202 

   203 To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`

   204 setting must be changed to use the

   205 :class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`::

   206 

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

   208 

   209 Example

   210 ^^^^^^^

   211 

   212 First, you'll need a bare-bones settings file, like below, that is

   213 customized with your spatial database name and user::

   214 

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

   216 

   217     DATABASES = {

   218         'default': {

   219             'ENGINE': 'django.contrib.gis.db.backends.postgis',

   220             'NAME': 'a_spatial_database',

   221             'USER': 'db_user'

   222         }

   223     }

   224 

   225 Assuming the above is in a file called ``postgis.py`` that is in the

   226 the same directory as ``manage.py`` of your Django project, then

   227 you may run the tests with the following command::

   228 

   229     $ python manage.py test --settings=postgis

   230 

   231 Run with ``runtests.py``

   232 ------------------------

   233 

   234 To have the GeoDjango tests executed when

   235 :ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``

   236 all of the databases in the settings file must be using one of the

   237 :ref:`spatial database backends <spatial-backends>`.

   238 

   239 .. warning::

   240 

   241     Do not change the :setting:`TEST_RUNNER` setting 

   242     when running the GeoDjango tests with ``runtests.py``.

   243 

   244 Example

   245 ^^^^^^^

   246 

   247 The following is an example bare-bones settings file with spatial backends

   248 that can be used to run the entire Django test suite, including those

   249 in :mod:`django.contrib.gis`::

   250 

   251     DATABASES = {

   252         'default': {

   253             'ENGINE': 'django.contrib.gis.db.backends.postgis',

   254             'NAME': 'geodjango',

   255             'USER': 'geodjango',

   256         },

   257        'other': {

   258             'ENGINE': 'django.contrib.gis.db.backends.postgis',

   259             'NAME': 'other',

   260             'USER': 'geodjango',

   261        }

   262     }

   263 

   264 Assuming the settings above were in a ``postgis.py`` file in the same

   265 directory as ``runtests.py``, then all Django and GeoDjango tests would

   266 be performed when executing the command::

   267 

   268     $ ./runtests.py --settings=postgis