1 files changed, 268 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/gis/testing.txt b/parts/django/docs/ref/contrib/gis/testing.txt
new file mode 100644
index 0000000..889b43a
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/testing.txt
@@ -0,0 +1,268 @@
+======================
+Testing GeoDjango Apps
+======================
+
+.. versionchanged:: 1.2
+
+In Django 1.2, the addition of :ref:`spatial-backends`
+simplified the process of testing GeoDjango applications.  Specifically, testing
+GeoDjango applications 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.
+
+.. note::
+
+    Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`.
+    See the :ref:`testing-1.1` section for more details.
+
+.. _testing-postgis:
+
+PostGIS
+=======
+
+Settings
+--------
+
+.. note::
+
+    The settings below have sensible defaults, and shouldn't require manual setting.
+
+.. setting:: POSTGIS_TEMPLATE
+
+``POSTGIS_TEMPLATE``
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+.. 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>`).
+
+.. note::
+
+    Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE`
+    with a value, for example::
+
+        POSTGIS_TEMPLATE='template_postgis'
+
+.. setting:: POSTGIS_VERSION
+
+``POSTGIS_VERSION``
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+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)::
+
+    postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
+
+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``
+
+Windows
+-------
+
+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:
+
+SpatiaLite
+==========
+
+.. versionadded:: 1.1
+
+You will need to download the `initialization SQL`__ script for SpatiaLite::
+
+    $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
+    $ unzip init_spatialite-2.3.zip
+
+If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``,
+then all you have to do is::
+
+    $ python manage.py test
+
+Settings
+--------
+
+.. setting:: SPATIALITE_SQL
+
+``SPATIALITE_SQL``
+^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+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
+``manage.py`` is located).  If you want to use a different location, then
+you may add the following to your settings::
+
+    SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'
+
+__ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
+
+.. _testing-1.1:
+
+Testing GeoDjango Applications in 1.1
+=====================================
+
+In Django 1.1, to accommodate the extra steps required to scaffalod a
+spatial database automatically, a test runner customized for GeoDjango
+must be used.  To use this runner, configure :setting:`TEST_RUNNER` as follows::
+
+    TEST_RUNNER='django.contrib.gis.tests.run_tests'
+
+.. note::
+
+    In order to create a spatial database, the :setting:`USER` setting
+    (or :setting:`TEST_USER`, if optionally defined on Oracle) requires
+    elevated privileges.  When using PostGIS or MySQL, the database user
+    must have at least the ability to create databases.  When testing on Oracle,
+    the user should be a superuser.
+
+.. _geodjango-tests:
+
+GeoDjango Tests
+===============
+
+.. versionchanged:: 1.2.4
+
+GeoDjango's test suite may be run in one of two ways, either by itself or
+with the rest of Django's :ref:`unit-tests`.
+
+.. note::
+
+    The :setting:`TEST_RUNNER` previously used to execute the GeoDjango
+    test suite,:func:`django.contrib.gis.tests.run_gis_tests`, was deprecated
+    in favor of the :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`
+    class.
+
+Run only GeoDjango tests
+------------------------
+
+To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`
+setting must be changed to use the
+:class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`::
+
+    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
+
+Example
+^^^^^^^
+
+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'
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.contrib.gis.db.backends.postgis',
+            'NAME': 'a_spatial_database',
+            'USER': 'db_user'
+        }
+    }
+
+Assuming the above is in a file called ``postgis.py`` that is in the
+the same directory as ``manage.py`` of your Django project, then
+you may run the tests with the following command::
+
+    $ python manage.py test --settings=postgis
+
+Run with ``runtests.py``
+------------------------
+
+To have the GeoDjango tests executed when
+:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
+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 ``runtests.py``.
+
+Example
+^^^^^^^
+
+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`::
+
+    DATABASES = {
+        '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 ``postgis.py`` file in the same
+directory as ``runtests.py``, then all Django and GeoDjango tests would
+be performed when executing the command::
+
+    $ ./runtests.py --settings=postgis