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