Improve documentation on how to run the GIS test suite

[Luke Plant]

Starting small, I'm attempting to use Spatialite to run the GIS testsuite (or at least the relevant parts), just because I need to run the GIS tests as a core developer.

First, the docs for this are very sketchy - the only thing I can find is this:

To run GeoDjango's own internal test suite, configure the TEST_RUNNER setting as follows:

  TEST_RUNNER='django.contrib.gis.tests.run_gis_tests'

Doing this in the obvious place i.e. a settings file and using runtests.py, produces this:

Traceback (most recent call last):                                                                    
  File "./runtests.py", line 314, in <module>
    failures = django_tests(int(options.verbosity), options.interactive, options.failfast, args)
  File "./runtests.py", line 180, in django_tests
    extra_tests=extra_tests)
  File "/home/luke/devel/django/trunk/django/contrib/gis/tests/__init__.py", line 19, in run_gis_tests
    return test_runner.run_tests(test_labels, extra_tests=extra_tests)
  File "/home/luke/devel/django/trunk/django/test/simple.py", line 311, in run_tests
    self.setup_test_environment()
  File "/home/luke/devel/django/trunk/django/contrib/gis/tests/__init__.py", line 37, in setup_test_environment
    if connection.ops.postgis and connection.ops.geography:
AttributeError: 'DatabaseOperations' object has no attribute 'postgis'

Also #10420 about this.

Using a test project and ./manage.py test instead, I get the following:

Traceback (most recent call last):
  File "./manage.py", line 11, in <module>
    execute_manager(settings)
  File "/home/luke/devel/django/trunk/django/core/management/__init__.py", line 438, in execute_manager
    utility.execute()
  File "/home/luke/devel/django/trunk/django/core/management/__init__.py", line 379, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/home/luke/devel/django/trunk/django/core/management/base.py", line 191, in run_from_argv
    self.execute(*args, **options.__dict__)
  File "/home/luke/devel/django/trunk/django/core/management/base.py", line 220, in execute
    output = self.handle(*args, **options)
  File "/home/luke/devel/django/trunk/django/core/management/commands/test.py", line 34, in handle
    failures = TestRunner(test_labels, verbosity=verbosity, interactive=interactive)
  File "/home/luke/devel/django/trunk/django/contrib/gis/tests/__init__.py", line 19, in run_gis_tests
    return test_runner.run_tests(test_labels, extra_tests=extra_tests)
  File "/home/luke/devel/django/trunk/django/test/simple.py", line 311, in run_tests
    self.setup_test_environment()
  File "/home/luke/devel/django/trunk/django/contrib/gis/tests/__init__.py", line 37, in setup_test_environment
    if connection.ops.postgis and connection.ops.geography:
AttributeError: 'DatabaseOperations' object has no attribute 'postgis'

I do have init_spatialite-2.3.sql in the working directory, not sure if that is needed.

[Luke Plant]

I've tried installing PostGIS, and using the 'postgresql_psycopg2' backend, but having the same problem.

[Alex Gaynor]

I believe you'd need to use "django.contrib.gis.db.backends.postgresql_psycopg2" to run the tests.

[jbronn]

You're trying to run GIS tests using the wrong database backend -- Alex is wrong, it's actually django.contrib.gis.db.backends.postgis.

Did you read the [spatial backend docs ​http://docs.djangoproject.com/en/dev/ref/contrib/gis/db-api/#spatial-backends]?

I don't see what I'm supposed to do with this ticket.

[Luke Plant]

I was looking for somewhere that would tell me what I need to know to run the GeoDjango tests, and found it frustrating that after more than an hour I hadn't been able to collect enough information from the different parts of the docs to be able to do this. I have finally succeeded in running them, at least with PostGIS. AFAICS, the process is to do something like:

1. Following the installation instructions for GeoDjango, and set up users/databases etc.
2. Create a throw-away a project using django-admin.py startproject
3. Change the settings to use the django.contrib.gis.db.backends.postgis backend
4. Add TEST_RUNNER='django.contrib.gis.tests.run_gis_tests' to the settings file (or, better, 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner', since the former produces deprecation warnings)

Number 1 is obvious, number 4 is documented ​here, but the rest is not obvious from the perspective of someone just wanting to run the tests.

It's absolutely fair enough to close as INVALID, since it's a pretty vague report, and I don't know what to do about it either. But I thought it was worthwhile noting it to someone.

[jbronn]

As of r14653, you no longer need a project settings file. The following will suffice for a settings file:

TEST_RUNNER='django.contrib.gis.tests.GeoDjangoTestSuiteRunner'

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'geodjango',
        'USER': 'geodjango',
    },
}

In other words, if the above were in a file called postgis.py, then django-admin.py test --settings=postgis would run the GeoDjango test suite.

[jbronn]

(In [15015]) Fixed #14439 -- Improved documentation for running the GeoDjango test suite.

[jbronn]

(In [15016]) [1.2.X] Fixed #14439 -- Improved documentation for running the GeoDjango test suite.

Backport of r15015 from trunk.