PageRenderTime 160ms CodeModel.GetById 156ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/ref/contrib/gis/testing.txt

https://code.google.com/p/mango-py/
Plain Text | 223 lines | 151 code | 72 blank | 0 comment | 0 complexity | 7df8d53be5425ccb453fcd5923699592 MD5 | raw file
  1======================
  2Testing GeoDjango Apps
  3======================
  4
  5.. versionchanged:: 1.2
  6
  7In Django 1.2, the addition of :ref:`spatial-backends` simplified the
  8process of testing GeoDjango applications -- the process is now the
  9same as :doc:`/topics/testing`.
 10
 11Included in this documentation are some additional notes and settings
 12for :ref:`testing-postgis` and :ref:`testing-spatialite` users.
 13
 14.. _testing-postgis:
 15
 16PostGIS
 17=======
 18
 19Settings
 20--------
 21
 22.. note::
 23
 24    The settings below have sensible defaults, and shouldn't require manual setting.
 25
 26.. setting:: POSTGIS_TEMPLATE
 27
 28``POSTGIS_TEMPLATE``
 29^^^^^^^^^^^^^^^^^^^^
 30
 31.. versionchanged:: 1.2
 32
 33This setting may be used to customize the name of the PostGIS template
 34database to use.  In Django versions 1.2 and above, it automatically
 35defaults to ``'template_postgis'`` (the same name used in the
 36:ref:`installation documentation <spatialdb_template>`).
 37
 38.. setting:: POSTGIS_VERSION
 39
 40``POSTGIS_VERSION``
 41^^^^^^^^^^^^^^^^^^^
 42
 43When GeoDjango's spatial backend initializes on PostGIS, it has to perform
 44a SQL query to determine the version in order to figure out what
 45features are available.  Advanced users wishing to prevent this additional
 46query may set the version manually using a 3-tuple of integers specifying
 47the major, minor, and subminor version numbers for PostGIS.  For example,
 48to configure for PostGIS 1.5.2 you would use::
 49
 50    POSTGIS_VERSION = (1, 5, 2)
 51
 52Obtaining Sufficient Privileges
 53-------------------------------
 54
 55Depending on your configuration, this section describes several methods to
 56configure a database user with sufficient privileges to run tests for
 57GeoDjango applications on PostgreSQL.  If your
 58:ref:`spatial database template <spatialdb_template>`
 59was created like in the instructions, then your testing database user
 60only needs to have the ability to create databases.  In other configurations,
 61you may be required to use a database superuser.
 62
 63Create Database User
 64^^^^^^^^^^^^^^^^^^^^
 65
 66To make database user with the ability to create databases, use the
 67following command::
 68
 69    $ createuser --createdb -R -S <user_name>
 70
 71The ``-R -S`` flags indicate that we do not want the user to have the ability
 72to create additional users (roles) or to be a superuser, respectively.
 73
 74Alternatively, you may alter an existing user's role from the SQL shell
 75(assuming this is done from an existing superuser account)::
 76
 77    postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
 78
 79Create Database Superuser
 80^^^^^^^^^^^^^^^^^^^^^^^^^
 81
 82This may be done at the time the user is created, for example::
 83
 84    $ createuser --superuser <user_name>
 85
 86Or you may alter the user's role from the SQL shell (assuming this
 87is done from an existing superuser account)::
 88
 89    postgres# ALTER ROLE <user_name> SUPERUSER;
 90
 91
 92Create Local PostgreSQL Database
 93^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 94
 951. Initialize database: ``initdb -D /path/to/user/db``
 96
 972. If there's already a Postgres instance on the machine, it will need
 98   to use a different TCP port than 5432. Edit ``postgresql.conf`` (in
 99   ``/path/to/user/db``) to change the database port (e.g. ``port = 5433``).
100
1013. Start this database ``pg_ctl -D /path/to/user/db start``
102
103Windows
104-------
105
106On Windows platforms the pgAdmin III utility may also be used as
107a simple way to add superuser privileges to your database user.
108
109By default, the PostGIS installer on Windows includes a template
110spatial database entitled ``template_postgis``.
111
112.. _testing-spatialite:
113
114SpatiaLite
115==========
116
117You will need to download the `initialization SQL`__ script for SpatiaLite::
118
119    $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
120    $ unzip init_spatialite-2.3.zip
121
122If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``,
123then all you have to do is::
124
125    $ python manage.py test
126
127Settings
128--------
129
130.. setting:: SPATIALITE_SQL
131
132``SPATIALITE_SQL``
133^^^^^^^^^^^^^^^^^^
134
135By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
136same directory where it was invoked (by default the same directory where
137``manage.py`` is located).  If you want to use a different location, then
138you may add the following to your settings::
139
140    SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'
141
142__ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
143
144
145.. _geodjango-tests:
146
147GeoDjango Tests
148===============
149
150.. versionchanged:: 1.3
151
152GeoDjango's test suite may be run in one of two ways, either by itself or
153with the rest of :ref:`Django's unit tests <unit-tests>`.
154
155Run only GeoDjango tests
156------------------------
157
158To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`
159setting must be changed to use the
160:class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`::
161
162    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
163
164Example
165^^^^^^^
166
167First, you'll need a bare-bones settings file, like below, that is
168customized with your spatial database name and user::
169
170    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
171
172    DATABASES = {
173        'default': {
174            'ENGINE': 'django.contrib.gis.db.backends.postgis',
175            'NAME': 'a_spatial_database',
176            'USER': 'db_user'
177        }
178    }
179
180Assuming the above is in a file called ``postgis.py`` that is in the
181the same directory as ``manage.py`` of your Django project, then
182you may run the tests with the following command::
183
184    $ python manage.py test --settings=postgis
185
186Run with ``runtests.py``
187------------------------
188
189To have the GeoDjango tests executed when
190:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
191all of the databases in the settings file must be using one of the
192:ref:`spatial database backends <spatial-backends>`.
193
194.. warning::
195
196    Do not change the :setting:`TEST_RUNNER` setting
197    when running the GeoDjango tests with ``runtests.py``.
198
199Example
200^^^^^^^
201
202The following is an example bare-bones settings file with spatial backends
203that can be used to run the entire Django test suite, including those
204in :mod:`django.contrib.gis`::
205
206    DATABASES = {
207        'default': {
208            'ENGINE': 'django.contrib.gis.db.backends.postgis',
209            'NAME': 'geodjango',
210            'USER': 'geodjango',
211        },
212       'other': {
213            'ENGINE': 'django.contrib.gis.db.backends.postgis',
214            'NAME': 'other',
215            'USER': 'geodjango',
216       }
217    }
218
219Assuming the settings above were in a ``postgis.py`` file in the same
220directory as ``runtests.py``, then all Django and GeoDjango tests would
221be performed when executing the command::
222
223    $ ./runtests.py --settings=postgis