<!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.6.7 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.6.7',
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.6.7 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.6.7 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, the database API and everything else in core Django core (<tt class="docutils literal"><span class="pre">tests/</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> or <tt class="docutils literal"><span class="pre">tests/<app>_...</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/overview.html"><em>Writing and running tests</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:</p>
<div class="highlight-bash"><div class="highlight"><pre>git clone https://github.com:django/django.git django-repo
<span class="nb">cd </span>django-repo/tests
<span class="nv">PYTHONPATH</span><span class="o">=</span>..:<span class="nv">$PYTHONPATH</span> python ./runtests.py --settings<span class="o">=</span>test_sqlite
</pre></div>
</div>
</div>
<div class="section" id="s-using-another-settings-module">
<span id="s-running-unit-tests-settings"></span><span id="using-another-settings-module"></span><span id="running-unit-tests-settings"></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, ensure that the module is on your
<tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> and pass the module with <tt class="docutils literal"><span class="pre">--settings</span></tt>.</p>
<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 any 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 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/</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.tests.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.tests.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="https://pypi.python.org/pypi/selenium">selenium</a> package (version > 2.13) into your Python path and run
the tests with the <tt class="docutils literal"><span class="pre">--selenium</span></tt> option:</p>
<div class="highlight-bash"><div class="highlight"><pre>./runtests.py --settings<span class="o">=</span>test_sqlite --selenium admin_inlines
</pre></div>
</div>
</div>
<div class="section" id="s-running-all-the-tests">
<span id="s-running-unit-tests-dependencies"></span><span id="running-all-the-tests"></span><span id="running-unit-tests-dependencies"></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="https://pypi.python.org/pypi/bcrypt">bcrypt</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/docutils">docutils</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/numpy">numpy</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/Pillow/">Pillow</a></li>
<li><a class="reference external" href="http://pyyaml.org/wiki/PyYAML">PyYAML</a></li>
<li><a class="reference external" href="https://pypi.python.org/pypi/pytz/">pytz</a></li>
<li><a class="reference external" href="https://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="https://pypi.python.org/pypi/selenium">selenium</a></li>
</ul>
<p>You can find these dependencies in <a class="reference external" href="http://www.pip-installer.org/en/latest/cookbook.html#requirements-files">pip requirements files</a> inside the
<tt class="docutils literal"><span class="pre">tests/requirements</span></tt> directory of the Django source tree and install them
like so:</p>
<div class="highlight-python"><pre>pip install -r tests/requirements/py2.txt # Python 3: py3.txt</pre>
</div>
<p>You can also install the database adapter(s) of your choice using
<tt class="docutils literal"><span class="pre">oracle.txt</span></tt>, <tt class="docutils literal"><span class="pre">mysql.txt</span></tt>, or <tt class="docutils literal"><span class="pre">postgres.txt</span></tt>.</p>
<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>To run the GeoDjango tests, you will need to <a class="reference internal" href="../../../ref/contrib/gis/install/index.html"><em>setup a spatial database
and install the Geospatial libraries</em></a>.</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/advanced.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">auth</span></tt>), use the same
method as above:</p>
<div class="highlight-python"><pre>./runtests.py --settings=settings django.contrib.auth</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.6.7 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">Sep 26, 2014</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>
