[1.2.X] Fixed #14439 -- Improved documentation for running the GeoDjango test suite. (a60d85aa) · Commits · Dom Sekotill / django

docs/internals/contributing.txt

+4 −0

Original line number	Diff line number	Diff line
		@@ -853,6 +853,8 @@ discovered, please follow these guidelines:
		* The release branch maintainer may back out commits to the release
		branch without permission if the commit breaks the release branch.

		.. _unit-tests:

		Unit tests
		==========

		@@ -871,6 +873,8 @@ The Django tests all use the testing infrastructure that ships with Django for
		testing applications. See :doc:`Testing Django applications </topics/testing>`
		for an explanation of how to write new tests.

		.. _running-unit-tests:

		Running the unit tests
		----------------------

docs/ref/contrib/gis/testing.txt

+95 −8

Original line number	Diff line number	Diff line
		@@ -53,13 +53,17 @@ defaults to ``'template_postgis'`` (the same name used in the

		``POSTGIS_VERSION``
		^^^^^^^^^^^^^^^^^^^

		.. versionadded:: 1.1

		When GeoDjango's spatial backend initializes on PostGIS, it has to perform
		a SQL query to determine the version. Setting the version manually
		prevents this query to the database::
		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.3.6', 1, 3, 6)
		POSTGIS_VERSION = (1, 5, 2)

		Obtaining Sufficient Privileges
		-------------------------------
		@@ -74,6 +78,7 @@ 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::

		@@ -89,6 +94,7 @@ Alternatively, you may alter an existing user's role from the SQL shell

		Create Database Superuser
		^^^^^^^^^^^^^^^^^^^^^^^^^

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

		$ createuser --superuser <user_name>
		@@ -112,6 +118,7 @@ Create Local PostgreSQL Database

		Windows
		-------

		On Windows platforms the pgAdmin III utility may also be used as
		a simple way to add superuser privileges to your database user.

		@@ -142,6 +149,7 @@ Settings

		``SPATIALITE_SQL``
		^^^^^^^^^^^^^^^^^^

		.. versionadded:: 1.1

		By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
		@@ -172,10 +180,89 @@ must be used. To use this runner, configure :setting:`TEST_RUNNER` as follows::
		must have at least the ability to create databases. When testing on Oracle,
		the user should be a superuser.

		GeoDjango Test Suite
		====================
		.. _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',
		}
		}

		To run GeoDjango's own internal test suite, configure the
		:setting:`TEST_RUNNER` setting as follows::
		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::

		TEST_RUNNER='django.contrib.gis.tests.run_gis_tests'
		$ ./runtests.py --settings=postgis

docs/releases/1.2.4.txt

+14 −1

Original line number	Diff line number	Diff line
		@@ -37,3 +37,16 @@ documentation on :ref:`controlling the creation order of test
		databases <topics-testing-creation-dependencies>` for details.

		.. _original problem report: http://code.djangoproject.com/ticket/14415

		GeoDjango
		=========

		The function-based :setting:`TEST_RUNNER` previously used to execute
		the GeoDjango test suite, :func:`django.contrib.gis.tests.run_gis_tests`,
		was finally deprecated in favor of a class-based test runner,
		:class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`, added in this
		release.

		In addition, the GeoDjango test suite is now included when
		:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
		and using :ref:`spatial database backends <spatial-backends>`.