<!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>Unit tests — Django 1.4.5 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.5', 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.5 documentation" href="../../../index.html" /> <link rel="up" title="Writing code" href="index.html" /> <link rel="next" title="Submitting patches" href="submitting-patches.html" /> <link rel="prev" title="Coding style" href="coding-style.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 = "../../../ref/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.5 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="coding-style.html" title="Coding style">previous</a> | <a href="../../index.html" title="Django internals" accesskey="U">up</a> | <a href="submitting-patches.html" title="Submitting patches">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="internals-contributing-writing-code-unit-tests"> <div class="section" id="s-unit-tests"> <span id="unit-tests"></span><h1>Unit tests<a class="headerlink" href="#unit-tests" title="Permalink to this headline">¶</a></h1> <p>Django comes with a test suite of its own, in the <tt class="docutils literal"><span class="pre">tests</span></tt> directory of the code base. It’s our policy to make sure all tests pass at all times.</p> <p>The tests cover:</p> <ul class="simple"> <li>Models and the database API (<tt class="docutils literal"><span class="pre">tests/modeltests</span></tt>),</li> <li>Everything else in core Django code (<tt class="docutils literal"><span class="pre">tests/regressiontests</span></tt>),</li> <li><a class="reference internal" href="#contrib-apps"><em>Contrib apps</em></a> (<tt class="docutils literal"><span class="pre">django/contrib/<app>/tests</span></tt>).</li> </ul> <p>We appreciate any and all contributions to the test suite!</p> <p>The Django tests all use the testing infrastructure that ships with Django for testing applications. See <a class="reference internal" href="../../../topics/testing.html"><em>Testing Django applications</em></a> for an explanation of how to write new tests.</p> <div class="section" id="s-running-the-unit-tests"> <span id="s-running-unit-tests"></span><span id="running-the-unit-tests"></span><span id="running-unit-tests"></span><h2>Running the unit tests<a class="headerlink" href="#running-the-unit-tests" title="Permalink to this headline">¶</a></h2> <div class="section" id="s-quickstart"> <span id="quickstart"></span><h3>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h3> <p>Running the tests requires a Django settings module that defines the databases to use. To make it easy to get started, Django provides a sample settings module that uses the SQLite database. To run the tests with this sample <tt class="docutils literal"><span class="pre">settings</span></tt> module, <tt class="docutils literal"><span class="pre">cd</span></tt> into the Django <tt class="docutils literal"><span class="pre">tests/</span></tt> directory and run:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>test_sqlite </pre></div> </div> <p>If you get an <tt class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">No</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">django.contrib</span></tt> error, you need to add your install of Django to your <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt>. For more details on how to do this, read <a class="reference internal" href="branch-policy.html#pointing-python-at-the-new-django-version"><em>Pointing Python at the new Django version</em></a>.</p> </div> <div class="section" id="s-using-another-settings-module"> <span id="using-another-settings-module"></span><h3>Using another <tt class="docutils literal"><span class="pre">settings</span></tt> module<a class="headerlink" href="#using-another-settings-module" title="Permalink to this headline">¶</a></h3> <p>The included settings module allows you to run the test suite using SQLite. If you want to test behavior using a different database (and if you’re proposing patches for Django, it’s a good idea to test across databases), you may need to define your own settings file.</p> <p>To run the tests with different settings, <tt class="docutils literal"><span class="pre">cd</span></tt> to the <tt class="docutils literal"><span class="pre">tests/</span></tt> directory and type:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>path.to.django.settings </pre></div> </div> <p>The <a class="reference internal" href="../../../ref/settings.html#std:setting-DATABASES"><tt class="xref std std-setting docutils literal"><span class="pre">DATABASES</span></tt></a> setting in this test settings module needs to define two databases:</p> <ul class="simple"> <li>A <tt class="docutils literal"><span class="pre">default</span></tt> database. This database should use the backend that you want to use for primary testing</li> <li>A database with the alias <tt class="docutils literal"><span class="pre">other</span></tt>. The <tt class="docutils literal"><span class="pre">other</span></tt> database is used to establish that queries can be directed to different databases. As a result, this database can use any backend you want. It doesn’t need to use the same backend as the <tt class="docutils literal"><span class="pre">default</span></tt> database (although it can use the same backend if you want to).</li> </ul> <p>If you’re using a backend that isn’t SQLite, you will need to provide other details for each database:</p> <ul class="simple"> <li>The <a class="reference internal" href="../../../ref/settings.html#std:setting-USER"><tt class="xref std std-setting docutils literal"><span class="pre">USER</span></tt></a> option for each of your databases needs to specify an existing user account for the database.</li> <li>The <a class="reference internal" href="../../../ref/settings.html#std:setting-PASSWORD"><tt class="xref std std-setting docutils literal"><span class="pre">PASSWORD</span></tt></a> option needs to provide the password for the <a class="reference internal" href="../../../ref/settings.html#std:setting-USER"><tt class="xref std std-setting docutils literal"><span class="pre">USER</span></tt></a> that has been specified.</li> <li>The <a class="reference internal" href="../../../ref/settings.html#std:setting-NAME"><tt class="xref std std-setting docutils literal"><span class="pre">NAME</span></tt></a> option must be the name of an existing database to which the given user has permission to connect. The unit tests will not touch this database; the test runner creates a new database whose name is <a class="reference internal" href="../../../ref/settings.html#std:setting-NAME"><tt class="xref std std-setting docutils literal"><span class="pre">NAME</span></tt></a> prefixed with <tt class="docutils literal"><span class="pre">test_</span></tt>, and this test database is deleted when the tests are finished. This means your user account needs permission to execute <tt class="docutils literal"><span class="pre">CREATE</span> <span class="pre">DATABASE</span></tt>.</li> </ul> <p>You will also need to ensure that your database uses UTF-8 as the default character set. If your database server doesn’t use UTF-8 as a default charset, you will need to include a value for <a class="reference internal" href="../../../ref/settings.html#std:setting-TEST_CHARSET"><tt class="xref std std-setting docutils literal"><span class="pre">TEST_CHARSET</span></tt></a> in the settings dictionary for the applicable database.</p> </div> <div class="section" id="s-running-only-some-of-the-tests"> <span id="running-only-some-of-the-tests"></span><h3>Running only some of the tests<a class="headerlink" href="#running-only-some-of-the-tests" title="Permalink to this headline">¶</a></h3> <p>Django’s entire test suite takes a while to run, and running every single test could be redundant if, say, you just added a test to Django that you want to run quickly without running everything else. You can run a subset of the unit tests by appending the names of the test modules to <tt class="docutils literal"><span class="pre">runtests.py</span></tt> on the command line.</p> <p>For example, if you’d like to run tests only for generic relations and internationalization, type:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>path.to.settings generic_relations i18n </pre></div> </div> <p>How do you find out the names of individual tests? Look in <tt class="docutils literal"><span class="pre">tests/modeltests</span></tt> and <tt class="docutils literal"><span class="pre">tests/regressiontests</span></tt> — each directory name there is the name of a test. Contrib app names are also valid test names.</p> <p>If you just want to run a particular class of tests, you can specify a list of paths to individual test classes. For example, to run the <tt class="docutils literal"><span class="pre">TranslationTests</span></tt> of the <tt class="docutils literal"><span class="pre">i18n</span></tt> module, type:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>path.to.settings i18n.TranslationTests </pre></div> </div> <p>Going beyond that, you can specify an individual test method like this:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>path.to.settings i18n.TranslationTests.test_lazy_objects </pre></div> </div> </div> <div class="section" id="s-running-the-selenium-tests"> <span id="running-the-selenium-tests"></span><h3>Running the Selenium tests<a class="headerlink" href="#running-the-selenium-tests" title="Permalink to this headline">¶</a></h3> <p>Some admin tests require Selenium 2, Firefox and Python >= 2.6 to work via a real Web browser. To allow those tests to run and not be skipped, you must install the <a class="reference external" href="http://pypi.python.org/pypi/selenium">selenium</a> package (version > 2.13) into your Python path.</p> <p>Then, run the tests normally, for example:</p> <div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>test_sqlite admin_inlines </pre></div> </div> </div> <div class="section" id="s-running-all-the-tests"> <span id="running-all-the-tests"></span><h3>Running all the tests<a class="headerlink" href="#running-all-the-tests" title="Permalink to this headline">¶</a></h3> <p>If you want to run the full suite of tests, you’ll need to install a number of dependencies:</p> <ul class="simple"> <li><a class="reference external" href="http://pyyaml.org/wiki/PyYAML">PyYAML</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/Markdown/1.7">Markdown</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/textile">Textile</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/docutils/0.4">Docutils</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/setuptools/">setuptools</a></li> <li><a class="reference external" href="http://memcached.org/">memcached</a>, plus a <a class="reference internal" href="../../../topics/cache.html#memcached"><em>supported Python binding</em></a></li> <li><a class="reference external" href="http://www.gnu.org/software/gettext/manual/gettext.html">gettext</a> (<a class="reference internal" href="../../../topics/i18n/translation.html#gettext-on-windows"><em>gettext on Windows</em></a>)</li> <li><a class="reference external" href="http://pypi.python.org/pypi/selenium">selenium</a> (if also using Python >= 2.6)</li> </ul> <p>If you want to test the memcached cache backend, you’ll also need to define a <a class="reference internal" href="../../../ref/settings.html#std:setting-CACHES"><tt class="xref std std-setting docutils literal"><span class="pre">CACHES</span></tt></a> setting that points at your memcached instance.</p> <p>Each of these dependencies is optional. If you’re missing any of them, the associated tests will be skipped.</p> </div> <div class="section" id="s-code-coverage"> <span id="code-coverage"></span><h3>Code coverage<a class="headerlink" href="#code-coverage" title="Permalink to this headline">¶</a></h3> <p>Contributors are encouraged to run coverage on the test suite to identify areas that need additional tests. The coverage tool installation and use is described in <a class="reference internal" href="../../../topics/testing.html#topics-testing-code-coverage"><em>testing code coverage</em></a>.</p> <p>To run coverage on the Django test suite using the standard test settings:</p> <div class="highlight-python"><pre>coverage run ./runtests.py --settings=test_sqlite</pre> </div> <p>After running coverage, generate the html report by running:</p> <div class="highlight-python"><pre>coverage html</pre> </div> <p>When running coverage for the Django tests, the included <tt class="docutils literal"><span class="pre">.coveragerc</span></tt> settings file defines <tt class="docutils literal"><span class="pre">coverage_html</span></tt> as the output directory for the report and also excludes several directories not relevant to the results (test code or external code included in Django).</p> </div> </div> <div class="section" id="s-contrib-apps"> <span id="s-id1"></span><span id="contrib-apps"></span><span id="id1"></span><h2>Contrib apps<a class="headerlink" href="#contrib-apps" title="Permalink to this headline">¶</a></h2> <p>Tests for contrib apps go in their respective directories under <tt class="docutils literal"><span class="pre">django/contrib</span></tt>, in a <tt class="docutils literal"><span class="pre">tests.py</span></tt> file. You can split the tests over multiple modules by using a <tt class="docutils literal"><span class="pre">tests</span></tt> directory in the normal Python way.</p> <p>For the tests to be found, a <tt class="docutils literal"><span class="pre">models.py</span></tt> file must exist, even if it’s empty. If you have URLs that need to be mapped, put them in <tt class="docutils literal"><span class="pre">tests/urls.py</span></tt>.</p> <p>To run tests for just one contrib app (e.g. <tt class="docutils literal"><span class="pre">markup</span></tt>), use the same method as above:</p> <div class="highlight-python"><pre>./runtests.py --settings=settings markup</pre> </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="#">Unit tests</a><ul> <li><a class="reference internal" href="#running-the-unit-tests">Running the unit tests</a><ul> <li><a class="reference internal" href="#quickstart">Quickstart</a></li> <li><a class="reference internal" href="#using-another-settings-module">Using another <tt class="docutils literal"><span class="pre">settings</span></tt> module</a></li> <li><a class="reference internal" href="#running-only-some-of-the-tests">Running only some of the tests</a></li> <li><a class="reference internal" href="#running-the-selenium-tests">Running the Selenium tests</a></li> <li><a class="reference internal" href="#running-all-the-tests">Running all the tests</a></li> <li><a class="reference internal" href="#code-coverage">Code coverage</a></li> </ul> </li> <li><a class="reference internal" href="#contrib-apps">Contrib apps</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="coding-style.html">Coding style</a></li> <li>Next: <a href="submitting-patches.html">Submitting patches</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../../index.html">Django 1.4.5 documentation</a> <ul><li><a href="../../index.html">Django internals</a> <ul><li><a href="../index.html">Contributing to Django</a> <ul><li><a href="index.html">Writing code</a> <ul><li>Unit tests</li></ul> </li></ul></li></ul></li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../../_sources/internals/contributing/writing-code/unit-tests.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">Feb 21, 2013</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="coding-style.html" title="Coding style">previous</a> | <a href="../../index.html" title="Django internals" accesskey="U">up</a> | <a href="submitting-patches.html" title="Submitting patches">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>