<!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.5.9 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.5.9', 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.5.9 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.5.9 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> <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> <p>This setting may be used to customize the name of the PostGIS template database to use. 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/postgis.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/postgis.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/spatialite.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 2.3.</p> <p>By default, the GeoDjango test runner looks for the <a class="reference internal" href="install/spatialite.html#create-spatialite-db"><em>file containing the SpatiaLite dababase-initialization SQL code</em></a> 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> <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> <dl class="class"> <dt id="django.contrib.gis.tests.GeoDjangoTestSuiteRunner"> <em class="property">class </em><tt class="descclassname">django.contrib.gis.tests.</tt><tt class="descname">GeoDjangoTestSuiteRunner</tt><a class="headerlink" href="#django.contrib.gis.tests.GeoDjangoTestSuiteRunner" title="Permalink to this definition">¶</a></dt> <dd></dd></dl> <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 <a class="reference internal" href="#django.contrib.gis.tests.GeoDjangoTestSuiteRunner" title="django.contrib.gis.tests.GeoDjangoTestSuiteRunner"><tt class="xref py py-class docutils literal"><span class="pre">GeoDjangoTestSuiteRunner</span></tt></a>:</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.5.9 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>