<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Testing GeoDjango apps — Django 1.4.18 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '1.4.18',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<link rel="top" title="Django 1.4.18 documentation" href="../../../index.html" />
<link rel="up" title="GeoDjango" href="index.html" />
<link rel="next" title="Deploying GeoDjango" href="deployment.html" />
<link rel="prev" title="Geographic Sitemaps" href="sitemaps.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.4.18 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="sitemaps.html" title="Geographic Sitemaps">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="deployment.html" title="Deploying GeoDjango">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-gis-testing">
<div class="section" id="s-testing-geodjango-apps">
<span id="testing-geodjango-apps"></span><h1>Testing GeoDjango apps<a class="headerlink" href="#testing-geodjango-apps" title="Permalink to this headline">¶</a></h1>
<div class="versionchanged">
<span class="title">Changed in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2.html"><em>Please see the release notes</em></a></div>
<p>In Django 1.2, the addition of <a class="reference internal" href="db-api.html#spatial-backends"><em>Spatial Backends</em></a> simplified the
process of testing GeoDjango applications. The process is now the
same as <a class="reference internal" href="../../../topics/testing.html"><em>Testing Django applications</em></a>.</p>
<p>Included in this documentation are some additional notes and settings
for <a class="reference internal" href="#testing-postgis"><em>PostGIS</em></a> and <a class="reference internal" href="#testing-spatialite"><em>SpatiaLite</em></a> users.</p>
<div class="section" id="s-postgis">
<span id="s-testing-postgis"></span><span id="postgis"></span><span id="testing-postgis"></span><h2>PostGIS<a class="headerlink" href="#postgis" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-settings">
<span id="settings"></span><h3>Settings<a class="headerlink" href="#settings" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The settings below have sensible defaults, and shouldn’t require manual setting.</p>
</div>
<div class="section" id="s-postgis-template">
<span id="s-std:setting-POSTGIS_TEMPLATE"></span><span id="postgis-template"></span><span id="std:setting-POSTGIS_TEMPLATE"></span><h4><tt class="docutils literal"><span class="pre">POSTGIS_TEMPLATE</span></tt><a class="headerlink" href="#postgis-template" title="Permalink to this headline">¶</a></h4>
<div class="versionchanged">
<span class="title">Changed in Django 1.2:</span> <a class="reference internal" href="../../../releases/1.2.html"><em>Please see the release notes</em></a></div>
<p>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 <tt class="docutils literal"><span class="pre">'template_postgis'</span></tt> (the same name used in the
<a class="reference internal" href="install.html#spatialdb-template"><em>installation documentation</em></a>).</p>
</div>
<div class="section" id="s-postgis-version">
<span id="s-std:setting-POSTGIS_VERSION"></span><span id="postgis-version"></span><span id="std:setting-POSTGIS_VERSION"></span><h4><tt class="docutils literal"><span class="pre">POSTGIS_VERSION</span></tt><a class="headerlink" href="#postgis-version" title="Permalink to this headline">¶</a></h4>
<p>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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">POSTGIS_VERSION</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-obtaining-sufficient-privileges">
<span id="obtaining-sufficient-privileges"></span><h3>Obtaining sufficient privileges<a class="headerlink" href="#obtaining-sufficient-privileges" title="Permalink to this headline">¶</a></h3>
<p>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
<a class="reference internal" href="install.html#spatialdb-template"><em>spatial database template</em></a>
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.</p>
<div class="section" id="s-create-database-user">
<span id="create-database-user"></span><h4>Create database user<a class="headerlink" href="#create-database-user" title="Permalink to this headline">¶</a></h4>
<p>To make a database user with the ability to create databases, use the
following command:</p>
<div class="highlight-python"><pre>$ createuser --createdb -R -S <user_name></pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">-R</span> <span class="pre">-S</span></tt> flags indicate that we do not want the user to have the ability
to create additional users (roles) or to be a superuser, respectively.</p>
<p>Alternatively, you may alter an existing user’s role from the SQL shell
(assuming this is done from an existing superuser account):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">postgres</span><span class="c"># ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-create-database-superuser">
<span id="create-database-superuser"></span><h4>Create database superuser<a class="headerlink" href="#create-database-superuser" title="Permalink to this headline">¶</a></h4>
<p>This may be done at the time the user is created, for example:</p>
<div class="highlight-python"><pre>$ createuser --superuser <user_name></pre>
</div>
<p>Or you may alter the user’s role from the SQL shell (assuming this
is done from an existing superuser account):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">postgres</span><span class="c"># ALTER ROLE <user_name> SUPERUSER;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-create-local-postgresql-database">
<span id="create-local-postgresql-database"></span><h4>Create local PostgreSQL database<a class="headerlink" href="#create-local-postgresql-database" title="Permalink to this headline">¶</a></h4>
<ol class="arabic simple">
<li>Initialize database: <tt class="docutils literal"><span class="pre">initdb</span> <span class="pre">-D</span> <span class="pre">/path/to/user/db</span></tt></li>
<li>If there’s already a Postgres instance on the machine, it will need
to use a different TCP port than 5432. Edit <tt class="docutils literal"><span class="pre">postgresql.conf</span></tt> (in
<tt class="docutils literal"><span class="pre">/path/to/user/db</span></tt>) to change the database port (e.g. <tt class="docutils literal"><span class="pre">port</span> <span class="pre">=</span> <span class="pre">5433</span></tt>).</li>
<li>Start this database <tt class="docutils literal"><span class="pre">pg_ctl</span> <span class="pre">-D</span> <span class="pre">/path/to/user/db</span> <span class="pre">start</span></tt></li>
</ol>
</div>
</div>
<div class="section" id="s-windows">
<span id="windows"></span><h3>Windows<a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3>
<p>On Windows platforms the pgAdmin III utility may also be used as
a simple way to add superuser privileges to your database user.</p>
<p>By default, the PostGIS installer on Windows includes a template
spatial database entitled <tt class="docutils literal"><span class="pre">template_postgis</span></tt>.</p>
</div>
</div>
<div class="section" id="s-spatialite">
<span id="s-testing-spatialite"></span><span id="spatialite"></span><span id="testing-spatialite"></span><h2>SpatiaLite<a class="headerlink" href="#spatialite" title="Permalink to this headline">¶</a></h2>
<p>Make sure the necessary spatial tables are created in your test spatial
database, as described in <a class="reference internal" href="install.html#create-spatialite-db"><em>Creating a spatial database for SpatiaLite</em></a>. Then just do this:</p>
<div class="highlight-python"><pre>$ python manage.py test</pre>
</div>
<div class="section" id="s-id1">
<span id="id1"></span><h3>Settings<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-spatialite-sql">
<span id="s-std:setting-SPATIALITE_SQL"></span><span id="spatialite-sql"></span><span id="std:setting-SPATIALITE_SQL"></span><h4><tt class="docutils literal"><span class="pre">SPATIALITE_SQL</span></tt><a class="headerlink" href="#spatialite-sql" title="Permalink to this headline">¶</a></h4>
<p>Only relevant when using a SpatiaLite version older than 3.0.</p>
<p>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
<tt class="docutils literal"><span class="pre">manage.py</span></tt> is located). To use a different location, add the following to
your settings:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">SPATIALITE_SQL</span><span class="o">=</span><span class="s">'/path/to/init_spatialite-2.3.sql'</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="s-geodjango-tests">
<span id="s-id2"></span><span id="geodjango-tests"></span><span id="id2"></span><h2>GeoDjango tests<a class="headerlink" href="#geodjango-tests" title="Permalink to this headline">¶</a></h2>
<div class="versionchanged">
<span class="title">Changed in Django 1.3:</span> <a class="reference internal" href="../../../releases/1.3.html"><em>Please see the release notes</em></a></div>
<p>GeoDjango’s test suite may be run in one of two ways, either by itself or
with the rest of <a class="reference internal" href="../../../internals/contributing/writing-code/unit-tests.html#running-unit-tests"><em>Django’s unit tests</em></a>.</p>
<div class="section" id="s-run-only-geodjango-tests">
<span id="run-only-geodjango-tests"></span><h3>Run only GeoDjango tests<a class="headerlink" href="#run-only-geodjango-tests" title="Permalink to this headline">¶</a></h3>
<p>To run <em>only</em> the tests for GeoDjango, the <a class="reference internal" href="../../settings.html#std:setting-TEST_RUNNER"><tt class="xref std std-setting docutils literal"><span class="pre">TEST_RUNNER</span></tt></a>
setting must be changed to use the
<tt class="xref py py-class docutils literal"><span class="pre">GeoDjangoTestSuiteRunner</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">TEST_RUNNER</span> <span class="o">=</span> <span class="s">'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'</span>
</pre></div>
</div>
<div class="section" id="s-example">
<span id="example"></span><h4>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h4>
<p>First, you’ll need a bare-bones settings file, like below, that is
customized with your spatial database name and user:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">TEST_RUNNER</span> <span class="o">=</span> <span class="s">'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'</span>
<span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'default'</span><span class="p">:</span> <span class="p">{</span>
<span class="s">'ENGINE'</span><span class="p">:</span> <span class="s">'django.contrib.gis.db.backends.postgis'</span><span class="p">,</span>
<span class="s">'NAME'</span><span class="p">:</span> <span class="s">'a_spatial_database'</span><span class="p">,</span>
<span class="s">'USER'</span><span class="p">:</span> <span class="s">'db_user'</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Assuming the above is in a file called <tt class="docutils literal"><span class="pre">postgis.py</span></tt> that is in the
the same directory as <tt class="docutils literal"><span class="pre">manage.py</span></tt> of your Django project, then
you may run the tests with the following command:</p>
<div class="highlight-python"><pre>$ python manage.py test --settings=postgis</pre>
</div>
</div>
</div>
<div class="section" id="s-run-with-runtests-py">
<span id="run-with-runtests-py"></span><h3>Run with <tt class="docutils literal"><span class="pre">runtests.py</span></tt><a class="headerlink" href="#run-with-runtests-py" title="Permalink to this headline">¶</a></h3>
<p>To have the GeoDjango tests executed when
<a class="reference internal" href="../../../internals/contributing/writing-code/unit-tests.html#running-unit-tests"><em>running the Django test suite</em></a> with <tt class="docutils literal"><span class="pre">runtests.py</span></tt>
all of the databases in the settings file must be using one of the
<a class="reference internal" href="db-api.html#spatial-backends"><em>spatial database backends</em></a>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do not change the <a class="reference internal" href="../../settings.html#std:setting-TEST_RUNNER"><tt class="xref std std-setting docutils literal"><span class="pre">TEST_RUNNER</span></tt></a> setting
when running the GeoDjango tests with <tt class="docutils literal"><span class="pre">runtests.py</span></tt>.</p>
</div>
<div class="section" id="s-id3">
<span id="id3"></span><h4>Example<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
<p>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 <a class="reference internal" href="index.html#module-django.contrib.gis" title="django.contrib.gis: Geographic Information System (GIS) extensions for Django"><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.gis</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">DATABASES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'default'</span><span class="p">:</span> <span class="p">{</span>
<span class="s">'ENGINE'</span><span class="p">:</span> <span class="s">'django.contrib.gis.db.backends.postgis'</span><span class="p">,</span>
<span class="s">'NAME'</span><span class="p">:</span> <span class="s">'geodjango'</span><span class="p">,</span>
<span class="s">'USER'</span><span class="p">:</span> <span class="s">'geodjango'</span><span class="p">,</span>
<span class="p">},</span>
<span class="s">'other'</span><span class="p">:</span> <span class="p">{</span>
<span class="s">'ENGINE'</span><span class="p">:</span> <span class="s">'django.contrib.gis.db.backends.postgis'</span><span class="p">,</span>
<span class="s">'NAME'</span><span class="p">:</span> <span class="s">'other'</span><span class="p">,</span>
<span class="s">'USER'</span><span class="p">:</span> <span class="s">'geodjango'</span><span class="p">,</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Assuming the settings above were in a <tt class="docutils literal"><span class="pre">postgis.py</span></tt> file in the same
directory as <tt class="docutils literal"><span class="pre">runtests.py</span></tt>, then all Django and GeoDjango tests would
be performed when executing the command:</p>
<div class="highlight-python"><pre>$ ./runtests.py --settings=postgis</pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Testing GeoDjango apps</a><ul>
<li><a class="reference internal" href="#postgis">PostGIS</a><ul>
<li><a class="reference internal" href="#settings">Settings</a><ul>
<li><a class="reference internal" href="#postgis-template"><tt class="docutils literal"><span class="pre">POSTGIS_TEMPLATE</span></tt></a></li>
<li><a class="reference internal" href="#postgis-version"><tt class="docutils literal"><span class="pre">POSTGIS_VERSION</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#obtaining-sufficient-privileges">Obtaining sufficient privileges</a><ul>
<li><a class="reference internal" href="#create-database-user">Create database user</a></li>
<li><a class="reference internal" href="#create-database-superuser">Create database superuser</a></li>
<li><a class="reference internal" href="#create-local-postgresql-database">Create local PostgreSQL database</a></li>
</ul>
</li>
<li><a class="reference internal" href="#windows">Windows</a></li>
</ul>
</li>
<li><a class="reference internal" href="#spatialite">SpatiaLite</a><ul>
<li><a class="reference internal" href="#id1">Settings</a><ul>
<li><a class="reference internal" href="#spatialite-sql"><tt class="docutils literal"><span class="pre">SPATIALITE_SQL</span></tt></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#geodjango-tests">GeoDjango tests</a><ul>
<li><a class="reference internal" href="#run-only-geodjango-tests">Run only GeoDjango tests</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#run-with-runtests-py">Run with <tt class="docutils literal"><span class="pre">runtests.py</span></tt></a><ul>
<li><a class="reference internal" href="#id3">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="sitemaps.html">Geographic Sitemaps</a></li>
<li>Next: <a href="deployment.html">Deploying GeoDjango</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../index.html">Django 1.4.18 documentation</a>
<ul><li><a href="../../index.html">API Reference</a>
<ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> packages</a>
<ul><li><a href="index.html">GeoDjango</a>
<ul><li>Testing GeoDjango apps</li></ul>
</li></ul></li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/gis/testing.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Jan 15, 2015</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="sitemaps.html" title="Geographic Sitemaps">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="deployment.html" title="Deploying GeoDjango">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
