Debian Codegraph @

docs/ref/contrib/gis/testing.txt

raw
1 ======================
2 Testing GeoDjango apps
3 ======================
4
5 Included in this documentation are some additional notes and settings
6 for :ref:`testing-postgis` users.
7
8 .. _testing-postgis:
9
10 PostGIS
11 =======
12
13 Settings
14 --------
15
16 .. note::
17
18 The settings below have sensible defaults, and shouldn't require manual setting.
19
20 .. setting:: POSTGIS_VERSION
21
22 ``POSTGIS_VERSION``
23 ~~~~~~~~~~~~~~~~~~~
24
25 When GeoDjango's spatial backend initializes on PostGIS, it has to perform
26 an SQL query to determine the version in order to figure out what
27 features are available. Advanced users wishing to prevent this additional
28 query may set the version manually using a 3-tuple of integers specifying
29 the major, minor, and micro version numbers for PostGIS. For example,
30 to configure for PostGIS X.Y.Z you would use::
31
32 POSTGIS_VERSION = (X, Y, Z)
33
34 Obtaining sufficient privileges
35 -------------------------------
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
45 Create database user
46 ~~~~~~~~~~~~~~~~~~~~
47
48 To make a database user with the ability to create databases, use the
49 following command:
50
51 .. code-block:: shell
52
53 $ createuser --createdb -R -S <user_name>
54
55 The ``-R -S`` flags indicate that we do not want the user to have the ability
56 to create additional users (roles) or to be a superuser, respectively.
57
58 Alternatively, you may alter an existing user's role from the SQL shell
59 (assuming this is done from an existing superuser account):
60
61 .. code-block:: psql
62
63 postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
64
65 Create database superuser
66 ~~~~~~~~~~~~~~~~~~~~~~~~~
67
68 This may be done at the time the user is created, for example:
69
70 .. code-block:: shell
71
72 $ createuser --superuser <user_name>
73
74 Or you may alter the user's role from the SQL shell (assuming this
75 is done from an existing superuser account):
76
77 .. code-block:: psql
78
79 postgres# ALTER ROLE <user_name> SUPERUSER;
80
81 Windows
82 -------
83
84 On Windows platforms you can use the pgAdmin III utility to add superuser
85 privileges to your database user.
86
87 By default, the PostGIS installer on Windows includes a template
88 spatial database entitled ``template_postgis``.
89
90 .. _geodjango-tests:
91
92 GeoDjango tests
93 ===============
94
95 To have the GeoDjango tests executed when :ref:`running the Django test suite
96 <running-unit-tests>` with ``runtests.py`` all of the databases in the settings
97 file must be using one of the :ref:`spatial database backends
98 <spatial-backends>`.
99
100
101 Example
102 -------
103
104 The following is an example bare-bones settings file with spatial backends
105 that can be used to run the entire Django test suite, including those
106 in :mod:`django.contrib.gis`::
107
108 DATABASES = {
109 "default": {
110 "ENGINE": "django.contrib.gis.db.backends.postgis",
111 "NAME": "geodjango",
112 "USER": "geodjango",
113 },
114 "other": {
115 "ENGINE": "django.contrib.gis.db.backends.postgis",
116 "NAME": "other",
117 "USER": "geodjango",
118 },
119 }
120
121 SECRET_KEY = "django_tests_secret_key"
122
123 Assuming the settings above were in a ``postgis.py`` file in the same
124 directory as ``runtests.py``, then all Django and GeoDjango tests would
125 be performed when executing the command:
126
127 .. code-block:: shell
128
129 $ ./runtests.py --settings=postgis
130
131 To run only the GeoDjango test suite, specify ``gis_tests``:
132
133 .. code-block:: shell
134
135 $ ./runtests.py --settings=postgis gis_tests