===========================
Testing Django applications
===========================

**New in Django development version**.

Automated testing is an extremely useful weapon in the bug-killing arsenal
of the modern developer. When initially writing code, a test suite can be
used to validate that code behaves as expected. When refactoring or
modifying code, tests serve as a guide to ensure that behavior hasn't
changed as a result of the refactor.

Testing an web application is a complex task, as there are many
components of a web application that must be validated and tested. To
help you test your application, Django provides a test execution
framework, and range of utilities that can be used to stimulate and
inspect various facets of a web application.

    This testing framework is currently under development, and may change
    slightly before the next official Django release.

    (That's *no* excuse not to write tests, though!)

Writing tests
=============

Tests in Django come in two forms: doctests and unit tests.

Writing doctests
----------------

Doctests use Python's standard doctest_ module, which searches for tests in
your docstrings. Django's test runner looks for doctests in your ``models.py``
file, and executes any that it finds. Django will also search for a file
called ``tests.py`` in the application directory (i.e., the directory that
holds ``models.py``). If a ``tests.py`` is found, it will also be searched
for doctests.

.. admonition:: What's a **docstring**?

    A good explanation of docstrings (and some guidlines for using them
    effectively) can be found in :PEP:`257`:

        A docstring is a string literal that occurs as the first statement in
        a module, function, class, or method definition.  Such a docstring
        becomes the ``__doc__`` special attribute of that object.

    Since tests often make great documentation, doctest lets you put your
    tests directly in your docstrings.

You can put doctest strings on any object in your ``models.py``, but it's
common practice to put application-level doctests in the module docstring, and
model-level doctests in the docstring for each model.

For example::

    from django.db import model

    class Animal(models.Model):
        """
        An animal that knows how to make noise

        # Create some animals
        >>> lion = Animal.objects.create(name="lion", sound="roar")
        >>> cat = Animal.objects.create(name="cat", sound="meow")

        # Make 'em speak
        >>> lion.speak()
        'The lion says "roar"'
        >>> cat.speak()
        'The cat says "meow"'
        """

        name = models.CharField(maxlength=20)
        sound = models.CharField(maxlength=20)

        def speak(self):
            return 'The %s says "%s"' % (self.name, self.sound)

When you `run your tests`_, the test utility will find this docstring, notice
that portions of it look like an interactive Python session, and execute those
lines while checking that the results match.

For more details about how doctest works, see the `standard library
documentation for doctest`_

.. _doctest: http://docs.python.org/lib/module-doctest.html
.. _standard library documentation for doctest: doctest_

Writing unittests
-----------------

Like doctests, Django's unit tests use a standard library module: unittest_.
As with doctests, Django's test runner looks for any unit test cases defined
in ``models.py``, or in a ``tests.py`` file in your application directory.

An equivalent unittest test case for the above example would look like::

    import unittest
    from myapp.models import Animal

    class AnimalTestCase(unittest.TestCase):

        def setUp(self):
            self.lion = Animal.objects.create(name="lion", sound="roar")
            self.cat = Animal.objects.create(name="cat", sound="meow")

        def testSpeaking(self):
            self.assertEquals(self.lion.speak(), 'The lion says "roar"')
            self.assertEquals(self.cat.speak(), 'The cat says "meow"')

When you `run your tests`_, the test utility will find all the test cases
(that is, subclasses of ``unittest.TestCase``) in ``tests.py``, automatically
build a test suite out of those test cases, and run that suite.

For more details about ``unittest``, see the `standard library unittest
documentation`_.

.. _unittest: http://docs.python.org/lib/module-unittest.html
.. _standard library unittest documentation: unittest_
.. _run your tests: `Running tests`_

Which should I use?
-------------------

Choosing a test framework is often contentious, so Django simply supports
both of the standard Python test frameworks. Choosing one is up to each
developer's personal tastes; each is supported equally. Since each test
system has different benefits, the best approach is probably to use both
together, picking the test system to match the type of tests you need to
write.

For developers new to testing, however, this choice can seem
confusing, so here are a few key differences to help you decide weather
doctests or unit tests are right for you.

If you've been using Python for a while, ``doctest`` will probably feel more
"pythonic". It's designed to make writing tests as easy as possible, so
there's no overhead of writing classes or methods; you simply put tests in
docstrings. This gives the added advantage of given your modules automatic
documentation -- well-written doctests can kill both the documentation and the
testing bird with a single stone.

For developers just getting started with testing, using doctests will probably
get you started faster.

The ``unittest`` framework will probably feel very familiar to developers
coming from Java.  Since ``unittest`` is inspired by Java's JUnit, if
you've used testing frameworks in other languages that similarly were
inspired by JUnit, ``unittest`` should also feel pretty familiar.

Since ``unittest`` is organized around classes and methods, if you need
to write a bunch of tests that all share similar code, you can easily use
subclass to abstract common tasks; this makes test code shorter and cleaner.
There's also support for explicit setup and/or cleanup routines, which give
you a high level of control over the environment your test cases run in.

Again, remember that you can use both systems side-by-side (even in the same
app). In the end, most projects will eventually end up using both; each shines
in different circumstances.

Testing utilities
=================

Test Client
-----------

A dummy browser; instruments the template generation process...

Fixtures
--------

Feature still to come...


Running tests
=============

Run your tests using your project's ``manage.py`` utility::

    $ ./manage.py test

If you only want to run tests for a particular application, add the
application name to the command line. For example, if your
``INSTALLED_APPS`` contains ``myproject.polls`` and ``myproject.animals``,
but you only want to run the animals unit tests, run::

    $ ./manage.py test animals

When you run your tests, you'll see a bunch of text flow by as the test
database is created and models are initialized. This test database is
created from scratch every time you run your tests. The test database
gets its name by prepending ``test_`` to the database name specified by
``settings.DATABASE_NAME``; all other database settings will the same as
they would be for the project normally.

Once the test database has been established, Django will run your tests.
If everything goes well, at the end you'll see::

    ----------------------------------------------------------------------
    Ran 22 tests in 0.221s

    OK

If there are test failures, however, you'll see full details about what tests
failed::

    ======================================================================
    FAIL: Doctest: ellington.core.throttle.models
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/dev/django/test/doctest.py", line 2153, in runTest
        raise self.failureException(self.format_failure(new.getvalue()))
    AssertionError: Failed doctest test for myapp.models
      File "/dev/myapp/models.py", line 0, in models

    ----------------------------------------------------------------------
    File "/dev/myapp/models.py", line 14, in myapp.models
    Failed example:
        throttle.check("actor A", "action one", limit=2, hours=1)
    Expected:
        True
    Got:
        False

    ----------------------------------------------------------------------
    Ran 2 tests in 0.048s

    FAILED (failures=1)

When the tests have all been executed, the test database is destroyed.

Using a different testing framework
===================================

Doctest and Unittest are not the only Python testing frameworks. While
Django doesn't provide explicit support these alternative frameworks,
it does provide a mechanism to allow you to invoke tests constructed for
an alternative framework as if they were normal Django tests.

When you run ``./manage.py test``, Django looks at the ``TEST_RUNNER``
setting to determine what to do. By default, ``TEST_RUNNER`` points to ``django.test.simple.run_tests``. This method defines the default Django
testing behaviour. This behaviour involves:

#. Creating the test database
#. Running ``syncdb`` to install models and initial data into the test database
#. Looking for Unit Tests and Doctests in ``models.py`` and ``tests.py`` file for each installed application
#. Running the Unit Tests and Doctests that are found
#. Destroying the test database.

If you define your own test runner method and point ``TEST_RUNNER``
at that method, Django will execute your test runner whenever you run
``./manage.py test``. In this way, it is possible to use any test
framework that can be executed from Python code.

Defining a test runner
----------------------
By convention, a test runner should be called ``run_tests``; however, you
can call it anything you want. The only requirement is that it accept two
arguments:

``run_tests(module_list, verbosity=1)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The module list is the list of Python modules that contain the models to be
tested. This is the same format returned by ``django.db.models.get_apps()``

Verbosity determines the amount of debug information that will be
provided to the console; '0' is no output, '1' is normal output,
and `2` is verbose output.

Testing utilities
-----------------

To assist in the creation of your own test runner, Django provides
a number of utility methods in the ``django.test.utils`` module.

``create_test_db(verbosity=1, autoclobber=False)``:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a new test database, and run ``syncdb`` against it.

``verbosity`` has the same behaviour as in the test runner.

``Autoclobber`` describes the behavior that will occur if a database with
the same name as the test database is discovered. If ``autoclobber`` is False,
the user will be asked to approve destroying the existing database. ``sys.exit``
is called if the user does not approve. If autoclobber is ``True``, the database
will be destroyed without consulting the user.

``create_test_db()`` has the side effect of modifying
``settings.DATABASE_NAME`` to match the name of the test database.

``destroy_test_db(old_database_name, verbosity=1)``:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Destroys the database with the name ``settings.DATABASE_NAME`` matching,
and restores the value of ``settings.DATABASE_NAME`` to the provided name.

``verbosity`` has the same behaviour as in the test runner.