1 ===========================
2 Testing Django applications
3 ===========================
5 Automated testing is an extremely useful bug-killing tool for the modern
6 Web developer. You can use a collection of tests -- a **test suite** -- to
7 solve, or avoid, a number of problems:
9 * When you're writing new code, you can use tests to validate your code
12 * When you're refactoring or modifying old code, you can use tests to
13 ensure your changes haven't affected your application's behavior
16 Testing a Web application is a complex task, because a Web application is made
17 of several layers of logic -- from HTTP-level request handling, to form
18 validation and processing, to template rendering. With Django's test-execution
19 framework and assorted utilities, you can simulate requests, insert test data,
20 inspect your application's output and generally verify your code is doing what
23 The best part is, it's really easy.
25 This document is split into two primary sections. First, we explain how to
26 write tests with Django. Then, we explain how to run them.
30 This testing framework is currently under development. It may change
31 slightly before the next official Django release.
33 (That's *no* excuse not to write tests, though!)
38 There are two primary ways to write tests with Django, corresponding to the
39 two test frameworks that ship in the Python standard library. The two
42 * **Doctests** -- tests that are embedded in your functions' docstrings and
43 are written in a way that emulates a session of the Python interactive
44 interpreter. For example::
46 def my_func(a_list, idx):
48 >>> a = ['larry', 'curly', 'moe']
56 * **Unit tests** -- tests that are expressed as methods on a Python class
57 that subclasses ``unittest.TestCase``. For example::
61 class MyFuncTestCase(unittest.TestCase)
63 a = ['larry', 'curly', 'moe']
64 self.assertEquals(my_func(a, 0), 'larry')
65 self.assertEquals(my_func(a, 1), 'curly')
67 You can choose the test framework you like, depending on which syntax you
68 prefer, or you can mix and match, using one framework for some of your code and
69 the other framework for other code. You can also use any *other* Python test
70 frameworks, as we'll explain in a bit.
75 Doctests use Python's standard doctest_ module, which searches your docstrings
76 for statements that resemble a session of the Python interactive interpreter.
77 A full explanation of how doctest works is out of the scope of this document;
78 read Python's official documentation for the details.
80 .. admonition:: What's a **docstring**?
82 A good explanation of docstrings (and some guidelines for using them
83 effectively) can be found in :PEP:`257`:
85 A docstring is a string literal that occurs as the first statement in
86 a module, function, class, or method definition. Such a docstring
87 becomes the ``__doc__`` special attribute of that object.
89 For example, this function has a docstring that describes what it does::
92 "Adds 2 to the given number and returns the result."
95 Because tests often make great documentation, putting tests directly in
96 your docstrings is an effective way to document *and* test your code.
98 For a given Django application, the test runner looks for doctests in two
101 * The ``models.py`` file. You can define module-level doctests and/or a
102 doctest for individual models. It's common practice to put
103 application-level doctests in the module docstring and model-level
104 doctests in the model docstrings.
106 * A file called ``tests.py`` in the application directory -- i.e., the
107 directory that holds ``models.py``. This file is a hook for any and all
108 doctests you want to write that aren't necessarily related to models.
110 Here is an example model doctest::
114 from django.db import models
116 class Animal(models.Model):
118 An animal that knows how to make noise
120 # Create some animals
121 >>> lion = Animal.objects.create(name="lion", sound="roar")
122 >>> cat = Animal.objects.create(name="cat", sound="meow")
126 'The lion says "roar"'
128 'The cat says "meow"'
130 name = models.CharField(max_length=20)
131 sound = models.CharField(max_length=20)
134 return 'The %s says "%s"' % (self.name, self.sound)
136 When you `run your tests`_, the test runner will find this docstring, notice
137 that portions of it look like an interactive Python session, and execute those
138 lines while checking that the results match.
140 In the case of model tests, note that the test runner takes care of
141 creating its own test database. That is, any test that accesses a
142 database -- by creating and saving model instances, for example --
143 will not affect your production database. Each doctest begins with a
144 "blank slate" -- a fresh database containing an empty table for each
145 model. (See the section on fixtures, below, for more on this.) Note
146 that to use this feature, the database user Django is connecting as
147 must have ``CREATE DATABASE`` rights.
149 For more details about how doctest works, see the `standard library
150 documentation for doctest`_
152 .. _doctest: http://docs.python.org/lib/module-doctest.html
153 .. _standard library documentation for doctest: doctest_
158 Like doctests, Django's unit tests use a standard library module: unittest_.
159 This module uses a different way of defining tests, taking a class-based
162 As with doctests, for a given Django application, the test runner looks for
163 unit tests in two places:
165 * The ``models.py`` file. The test runner looks for any subclass of
166 ``unittest.TestCase`` in this module.
168 * A file called ``tests.py`` in the application directory -- i.e., the
169 directory that holds ``models.py``. Again, the test runner looks for any
170 subclass of ``unittest.TestCase`` in this module.
172 This example ``unittest.TestCase`` subclass is equivalent to the example given
173 in the doctest section above::
176 from myapp.models import Animal
178 class AnimalTestCase(unittest.TestCase):
180 self.lion = Animal.objects.create(name="lion", sound="roar")
181 self.cat = Animal.objects.create(name="cat", sound="meow")
183 def testSpeaking(self):
184 self.assertEquals(self.lion.speak(), 'The lion says "roar"')
185 self.assertEquals(self.cat.speak(), 'The cat says "meow"')
187 When you `run your tests`_, the default behavior of the test utility is
188 to find all the test cases (that is, subclasses of ``unittest.TestCase``)
189 in ``models.py`` and ``tests.py``, automatically build a test suite out of
190 those test cases, and run that suite.
192 In the Django development version, there is a second way to define the test
193 suite for a module: if you define a function called ``suite()`` in either
194 ``models.py`` or ``tests.py``, the Django test runner will use that function
195 to construct the test suite for that module. This follows the
196 `suggested organization`_ for unit tests. See the Python documentation for
197 more details on how to construct a complex test suite.
199 For more details about ``unittest``, see the `standard library unittest
202 .. _unittest: http://docs.python.org/lib/module-unittest.html
203 .. _standard library unittest documentation: unittest_
204 .. _run your tests: `Running tests`_
205 .. _suggested organization: http://docs.python.org/lib/organizing-tests.html
210 Because Django supports both of the standard Python test frameworks, it's up to
211 you and your tastes to decide which one to use. You can even decide to use
214 For developers new to testing, however, this choice can seem confusing. Here,
215 then, are a few key differences to help you decide which approach is right for
218 * If you've been using Python for a while, ``doctest`` will probably feel
219 more "pythonic". It's designed to make writing tests as easy as possible,
220 so it requires no overhead of writing classes or methods. You simply put
221 tests in docstrings. This has the added advantage of serving as
222 documentation (and correct documentation, at that!).
224 If you're just getting started with testing, using doctests will probably
225 get you started faster.
227 * The ``unittest`` framework will probably feel very familiar to developers
228 coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll
229 feel at home with this method if you've used JUnit or any test framework
232 * If you need to write a bunch of tests that share similar code, then
233 you'll appreciate the ``unittest`` framework's organization around
234 classes and methods. This makes it easy to abstract common tasks into
235 common methods. The framework also supports explicit setup and/or cleanup
236 routines, which give you a high level of control over the environment
237 in which your test cases are run.
239 Again, remember that you can use both systems side-by-side (even in the same
240 app). In the end, most projects will eventually end up using both. Each shines
241 in different circumstances.
246 Once you've written tests, run them using your project's ``manage.py`` utility::
250 By default, this will run every test in every application in ``INSTALLED_APPS``.
251 If you only want to run tests for a particular application, add the
252 application name to the command line. For example, if your ``INSTALLED_APPS``
253 contains ``'myproject.polls'`` and ``'myproject.animals'``, you can run the
254 ``myproject.animals`` unit tests alone with this command::
256 # ./manage.py test animals
258 Note that we used ``animals``, not ``myproject.animals``.
260 **New in Django development version:** If you use unit tests, as opposed to
261 doctests, you can be even *more* specific in choosing which tests to execute.
262 To run a single test case in an application (for example, the
263 ``AnimalTestCase`` described in the "Writing unit tests" section), add the
264 name of the test case to the label on the command line::
266 $ ./manage.py test animals.AnimalTestCase
268 And it gets even more granular than that! To run a *single* test method inside
269 a test case, add the name of the test method to the label::
271 $ ./manage.py test animals.AnimalTestCase.testFluffyAnimals
273 Understanding the test output
274 -----------------------------
276 When you run your tests, you'll see a number of messages as the test runner
279 Creating test database...
280 Creating table myapp_animal
281 Creating table myapp_mineral
282 Loading 'initial_data' fixtures...
285 This tells you that the test runner is creating a test database -- a blank,
286 from-scratch database that it will use for any tests that happen to require a
287 database (namely, model tests).
289 Don't worry -- the test runner will not touch your "real" (production)
290 database. It creates a separate database purely for the tests. This test
291 database gets its name by prepending ``test_`` to the value of the
292 ``DATABASE_NAME`` setting. If you want to use a different name, specify the
293 ``TEST_DATABASE_NAME`` setting.
295 Aside from using a separate database, the test runner will otherwise use all of
296 the same database settings you have in your settings file: ``DATABASE_ENGINE``,
297 ``DATABASE_USER``, ``DATABASE_HOST``, etc. The test database is created by the
298 user specified by ``DATABASE_USER``, so you'll need to make sure that the given
299 user account has sufficient privileges to create a new database on the system.
301 **New in Django development version:** For fine-grained control over the
302 character encoding of your test database, use the ``TEST_DATABASE_CHARSET``
303 setting. If you're using MySQL, you can also use the ``TEST_DATABASE_COLLATION``
304 setting to control the particular collation used by the test database. See the
305 settings_ documentation for details of these advanced settings.
307 .. _settings: ../settings/
309 Once the test database has been created, Django will run your tests.
310 If everything goes well, you'll see something like this::
312 ----------------------------------------------------------------------
313 Ran 22 tests in 0.221s
317 If there are test failures, however, you'll see full details about which tests
320 ======================================================================
321 FAIL: Doctest: ellington.core.throttle.models
322 ----------------------------------------------------------------------
323 Traceback (most recent call last):
324 File "/dev/django/test/doctest.py", line 2153, in runTest
325 raise self.failureException(self.format_failure(new.getvalue()))
326 AssertionError: Failed doctest test for myapp.models
327 File "/dev/myapp/models.py", line 0, in models
329 ----------------------------------------------------------------------
330 File "/dev/myapp/models.py", line 14, in myapp.models
332 throttle.check("actor A", "action one", limit=2, hours=1)
338 ----------------------------------------------------------------------
339 Ran 2 tests in 0.048s
343 A full explanation of this error output is beyond the scope of this document,
344 but it's pretty intuitive. You can consult the documentation of Python's
345 ``unittest`` library for details.
347 Note that the return code for the test-runner script is the total number of
348 failed and erroneous tests. If all the tests pass, the return code is 0. This
349 feature is useful if you're using the test-runner script in a shell script and
350 need to test for success or failure at that level.
352 Regardless of whether the tests pass or fail, the test database is destroyed when
353 all the tests have been executed.
358 Django provides a small set of tools that come in handy when writing tests.
363 The test client is a Python class that acts as a dummy Web browser, allowing
364 you to test your views and interact with your Django-powered application
367 Some of the things you can do with the test client are:
369 * Simulate GET and POST requests on a URL and observe the response --
370 everything from low-level HTTP (result headers and status codes) to
373 * Test that the correct view is executed for a given URL.
375 * Test that a given request is rendered by a given Django template, with
376 a template context that contains certain values.
378 Note that the test client is not intended to be a replacement for Twill_,
379 Selenium_, or other "in-browser" frameworks. Django's test client has
380 a different focus. In short:
382 * Use Django's test client to establish that the correct view is being
383 called and that the view is collecting the correct context data.
385 * Use in-browser frameworks such as Twill and Selenium to test *rendered*
386 HTML and the *behavior* of Web pages, namely JavaScript functionality.
388 A comprehensive test suite should use a combination of both test types.
390 .. _Twill: http://twill.idyll.org/
391 .. _Selenium: http://www.openqa.org/selenium/
393 Overview and a quick example
394 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
396 To use the test client, instantiate ``django.test.client.Client`` and retrieve
399 >>> from django.test.client import Client
401 >>> response = c.post('/login/', {'username': 'john', 'password': 'smith'})
402 >>> response.status_code
404 >>> response = c.get('/customer/details/')
406 '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...'
408 As this example suggests, you can instantiate ``Client`` from within a session
409 of the Python interactive interpreter.
411 Note a few important things about how the test client works:
413 * The test client does *not* require the Web server to be running. In fact,
414 it will run just fine with no Web server running at all! That's because
415 it avoids the overhead of HTTP and deals directly with the Django
416 framework. This helps make the unit tests run quickly.
418 * When retrieving pages, remember to specify the *path* of the URL, not the
419 whole domain. For example, this is correct::
425 >>> c.get('http://www.example.com/login/')
427 The test client is not capable of retrieving Web pages that are not
428 powered by your Django project. If you need to retrieve other Web pages,
429 use a Python standard library module such as urllib_ or urllib2_.
431 * To resolve URLs, the test client uses whatever URLconf is pointed-to by
432 your ``ROOT_URLCONF`` setting.
434 * Although the above example would work in the Python interactive
435 interpreter, some of the test client's functionality, notably the
436 template-related functionality, is only available *while tests are running*.
438 The reason for this is that Django's test runner performs a bit of black
439 magic in order to determine which template was loaded by a given view.
440 This black magic (essentially a patching of Django's template system in
441 memory) only happens during test running.
443 .. _urllib: http://docs.python.org/lib/module-urllib.html
444 .. _urllib2: http://docs.python.org/lib/module-urllib2.html
449 Use the ``django.test.client.Client`` class to make requests. It requires no
450 arguments at time of construction::
454 Once you have a ``Client`` instance, you can call any of the following methods:
456 ``get(path, data={})``
457 Makes a GET request on the provided ``path`` and returns a ``Response``
458 object, which is documented below.
460 The key-value pairs in the ``data`` dictionary are used to create a GET
461 data payload. For example::
464 >>> c.get('/customers/details/', {'name': 'fred', 'age': 7})
466 ...will result in the evaluation of a GET request equivalent to::
468 /customers/details/?name=fred&age=7
470 ``post(path, data={}, content_type=MULTIPART_CONTENT)``
471 Makes a POST request on the provided ``path`` and returns a ``Response``
472 object, which is documented below.
474 The key-value pairs in the ``data`` dictionary are used to submit POST
478 >>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})
480 ...will result in the evaluation of a POST request to this URL::
484 ...with this POST data::
486 name=fred&passwd=secret
488 If you provide ``content_type`` (e.g., ``text/xml`` for an XML payload),
489 the contents of ``data`` will be sent as-is in the POST request, using
490 ``content_type`` in the HTTP ``Content-Type`` header.
492 If you don't provide a value for ``content_type``, the values in
493 ``data`` will be transmitted with a content type of ``multipart/form-data``.
494 In this case, the key-value pairs in ``data`` will be encoded as a
495 multipart message and used to create the POST data payload.
497 To submit multiple values for a given key -- for example, to specify
498 the selections for a ``<select multiple>`` -- provide the values as a
499 list or tuple for the required key. For example, this value of ``data``
500 would submit three selected values for the field named ``choices``::
502 {'choices': ('a', 'b', 'd')}
504 Submitting files is a special case. To POST a file, you need only provide
505 the file field name as a key, and a file handle to the file you wish to
506 upload as a value. For example::
509 >>> f = open('wishlist.doc')
510 >>> c.post('/customers/wishes/', {'name': 'fred', 'attachment': f})
513 (The name ``attachment`` here is not relevant; use whatever name your
514 file-processing code expects.)
516 Note that you should manually close the file after it has been provided to
519 ``login(**credentials)``
520 **New in Django development version**
522 If your site uses Django's `authentication system`_ and you deal with
523 logging in users, you can use the test client's ``login()`` method to
524 simulate the effect of a user logging into the site.
526 After you call this method, the test client will have all the cookies and
527 session data required to pass any login-based tests that may form part of
530 The format of the ``credentials`` argument depends on which
531 `authentication backend`_ you're using (which is configured by your
532 ``AUTHENTICATION_BACKENDS`` setting). If you're using the standard
533 authentication backend provided by Django (``ModelBackend``),
534 ``credentials`` should be the user's username and password, provided as
538 >>> c.login(username='fred', password='secret')
539 >>> # Now you can access a view that's only available to logged-in users.
541 If you're using a different authentication backend, this method may require
542 different credentials. It requires whichever credentials are required by
543 your backend's ``authenticate()`` method.
545 ``login()`` returns ``True`` if it the credentials were accepted and login
548 Finally, you'll need to remember to create user accounts before you can use
549 this method. As we explained above, the test runner is executed using a
550 test database, which contains no users by default. As a result, user
551 accounts that are valid on your production site will not work under test
552 conditions. You'll need to create users as part of the test suite -- either
553 manually (using the Django model API) or with a test fixture.
556 **New in Django development version**
558 If your site uses Django's `authentication system`_, the ``logout()``
559 method can be used to simulate the effect of a user logging out of
562 After you call this method, the test client will have all the cookies and
563 session data cleared to defaults. Subsequent requests will appear to
564 come from an AnonymousUser.
566 .. _authentication system: ../authentication/
567 .. _authentication backend: ../authentication/#other-authentication-sources
572 The ``get()`` and ``post()`` methods both return a ``Response`` object. This
573 ``Response`` object is *not* the same as the ``HttpResponse`` object returned
574 Django views; the test response object has some additional data useful for
577 Specifically, a ``Response`` object has the following attributes:
579 =============== ==========================================================
580 Attribute Description
581 =============== ==========================================================
582 ``client`` The test client that was used to make the request that
583 resulted in the response.
585 ``content`` The body of the response, as a string. This is the final
586 page content as rendered by the view, or any error
589 ``context`` The template ``Context`` instance that was used to render
590 the template that produced the response content.
592 If the rendered page used multiple templates, then
593 ``context`` will be a list of ``Context``
594 objects, in the order in which they were rendered.
596 ``headers`` The HTTP headers of the response. This is a dictionary.
598 ``request`` The request data that stimulated the response.
600 ``status_code`` The HTTP status of the response, as an integer. See
601 RFC2616_ for a full list of HTTP status codes.
603 ``template`` The ``Template`` instance that was used to render the
604 final content. Use ``template.name`` to get the
605 template's file name, if the template was loaded from a
606 file. (The name is a string such as
607 ``'admin/index.html'``.)
609 If the rendered page used multiple templates -- e.g.,
610 using `template inheritance`_ -- then ``template`` will
611 be a list of ``Template`` instances, in the order in
612 which they were rendered.
613 =============== ==========================================================
615 .. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
616 .. _template inheritance: ../templates/#template-inheritance
621 If you point the test client at a view that raises an exception, that exception
622 will be visible in the test case. You can then use a standard ``try...catch``
623 block or ``unittest.TestCase.assertRaises()`` to test for exceptions.
625 The only exceptions that are not visible to the test client are ``Http404``,
626 ``PermissionDenied`` and ``SystemExit``. Django catches these exceptions
627 internally and converts them into the appropriate HTTP response codes. In these
628 cases, you can check ``response.status_code`` in your test.
633 The test client is stateful. If a response returns a cookie, then that cookie
634 will be stored in the test client and sent with all subsequent ``get()`` and
637 Expiration policies for these cookies are not followed. If you want a cookie
638 to expire, either delete it manually or create a new ``Client`` instance (which
639 will effectively delete all cookies).
641 A test client has two attributes that store persistent state information. You
642 can access these properties as part of a test condition.
644 =============== ==========================================================
645 Attribute Description
646 =============== ==========================================================
647 ``cookies`` A Python ``SimpleCookie`` object, containing the current
648 values of all the client cookies. See the
649 `Cookie module documentation`_ for more.
651 ``session`` A dictionary-like object containing session information.
652 See the `session documentation`_ for full details.
653 =============== ==========================================================
655 .. _Cookie module documentation: http://docs.python.org/lib/module-Cookie.html
656 .. _session documentation: ../sessions/
661 The following is a simple unit test using the test client::
664 from django.test.client import Client
666 class SimpleTest(unittest.TestCase):
668 # Every test needs a client.
669 self.client = Client()
671 def test_details(self):
672 # Issue a GET request.
673 response = self.client.get('/customer/details/')
675 # Check that the respose is 200 OK.
676 self.failUnlessEqual(response.status_code, 200)
678 # Check that the rendered context contains 5 customers.
679 self.failUnlessEqual(len(response.context['customers']), 5)
684 Normal Python unit test classes extend a base class of ``unittest.TestCase``.
685 Django provides an extension of this base class -- ``django.test.TestCase``
686 -- that provides some additional capabilities that can be useful for
689 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
690 just change the base class of your test from ``unittest.TestCase`` to
691 ``django.test.TestCase``. All of the standard Python unit test functionality
692 will continue to be available, but it will be augmented with some useful
698 **New in Django development version**
700 Every test case in a ``django.test.TestCase`` instance has access to an
701 instance of a Django test client. This client can be accessed as
702 ``self.client``. This client is recreated for each test, so you don't have to
703 worry about state (such as cookies) carrying over from one test to another.
705 This means, instead of instantiating a ``Client`` in each test::
708 from django.test.client import Client
710 class SimpleTest(unittest.TestCase):
711 def test_details(self):
713 response = client.get('/customer/details/')
714 self.failUnlessEqual(response.status_code, 200)
716 def test_index(self):
718 response = client.get('/customer/index/')
719 self.failUnlessEqual(response.status_code, 200)
721 ...you can just refer to ``self.client``, like so::
723 from django.test import TestCase
725 class SimpleTest(TestCase):
726 def test_details(self):
727 response = self.client.get('/customer/details/')
728 self.failUnlessEqual(response.status_code, 200)
730 def test_index(self):
731 response = self.client.get('/customer/index/')
732 self.failUnlessEqual(response.status_code, 200)
737 A test case for a database-backed Web site isn't much use if there isn't any
738 data in the database. To make it easy to put test data into the database,
739 Django's custom ``TestCase`` class provides a way of loading **fixtures**.
741 A fixture is a collection of data that Django knows how to import into a
742 database. For example, if your site has user accounts, you might set up a
743 fixture of fake user accounts in order to populate your database during tests.
745 The most straightforward way of creating a fixture is to use the
746 ``manage.py dumpdata`` command. This assumes you already have some data in
747 your database. See the `dumpdata documentation`_ for more details.
750 If you've ever run ``manage.py syncdb``, you've already used a fixture
751 without even knowing it! When you call ``syncdb`` in the database for
752 the first time, Django installs a fixture called ``initial_data``.
753 This gives you a way of populating a new database with any initial data,
754 such as a default set of categories.
756 Fixtures with other names can always be installed manually using the
757 ``manage.py loaddata`` command.
759 Once you've created a fixture and placed it somewhere in your Django project,
760 you can use it in your unit tests by specifying a ``fixtures`` class attribute
761 on your ``django.test.TestCase`` subclass::
763 from django.test import TestCase
764 from myapp.models import Animal
766 class AnimalTestCase(TestCase):
767 fixtures = ['mammals.json', 'birds']
770 # Test definitions as before.
772 def testFluffyAnimals(self):
773 # A test that uses the fixtures.
775 Here's specifically what will happen:
777 * At the start of each test case, before ``setUp()`` is run, Django will
778 flush the database, returning the database to the state it was in
779 directly after ``syncdb`` was called.
781 * Then, all the named fixtures are installed. In this example, Django will
782 install any JSON fixture named ``mammals``, followed by any fixture named
783 ``birds``. See the `loaddata documentation`_ for more details on defining
784 and installing fixtures.
786 This flush/load procedure is repeated for each test in the test case, so you
787 can be certain that the outcome of a test will not be affected by
788 another test, or by the order of test execution.
790 .. _dumpdata documentation: ../django-admin/#dumpdata-appname-appname
791 .. _loaddata documentation: ../django-admin/#loaddata-fixture-fixture
793 Emptying the test outbox
794 ~~~~~~~~~~~~~~~~~~~~~~~~
796 **New in Django development version**
798 If you use Django's custom ``TestCase`` class, the test runner will clear the
799 contents of the test e-mail outbox at the start of each test case.
801 For more detail on e-mail services during tests, see `E-mail services`_.
806 **New in Django development version**
808 As Python's normal ``unittest.TestCase`` class implements assertion
809 methods such as ``assertTrue`` and ``assertEquals``, Django's custom
810 ``TestCase`` class provides a number of custom assertion methods that are
811 useful for testing Web applications:
813 ``assertContains(response, text, count=None, status_code=200)``
814 Asserts that a ``Response`` instance produced the given ``status_code`` and
815 that ``text`` appears in the content of the response. If ``count`` is
816 provided, ``text`` must occur exactly ``count`` times in the response.
818 ``assertFormError(response, form, field, errors)``
819 Asserts that a field on a form raises the provided list of errors when
820 rendered on the form.
822 ``form`` is the name the ``Form`` instance was given in the template
823 context. Note that this works only for ``newforms.Form`` instances, not
824 ``oldforms.Form`` instances.
826 ``field`` is the name of the field on the form to check. If ``field``
827 has a value of ``None``, non-field errors (errors you can access via
828 ``form.non_field_errors()``) will be checked.
830 ``errors`` is an error string, or a list of error strings, that are
831 expected as a result of form validation.
833 ``assertTemplateNotUsed(response, template_name)``
834 Asserts that the template with the given name was *not* used in rendering
837 ``assertRedirects(response, expected_url, status_code=302, target_status_code=200)``
838 Asserts that the response return a ``status_code`` redirect status,
839 it redirected to ``expected_url`` (including any GET data), and the subsequent
840 page was received with ``target_status_code``.
842 ``assertTemplateUsed(response, template_name)``
843 Asserts that the template with the given name was used in rendering the
846 The name is a string such as ``'admin/index.html'``.
851 **New in Django development version**
853 If any of your Django views send e-mail using `Django's e-mail functionality`_,
854 you probably don't want to send e-mail each time you run a test using that
855 view. For this reason, Django's test runner automatically redirects all
856 Django-sent e-mail to a dummy outbox. This lets you test every aspect of
857 sending e-mail -- from the number of messages sent to the contents of each
858 message -- without actually sending the messages.
860 The test runner accomplishes this by transparently replacing the normal
861 `SMTPConnection`_ class with a different version. (Don't worry -- this has no
862 effect on any other e-mail senders outside of Django, such as your machine's
863 mail server, if you're running one.)
865 During test running, each outgoing e-mail is saved in
866 ``django.core.mail.outbox``. This is a simple list of all `EmailMessage`_
867 instances that have been sent. It does not exist under normal execution
868 conditions, i.e., when you're not running unit tests. The outbox is created
869 during test setup, along with the dummy `SMTPConnection`_. When the test
870 framework is torn down, the standard `SMTPConnection`_ class is restored, and
871 the test outbox is destroyed.
873 Here's an example test that examines ``django.core.mail.outbox`` for length
876 from django.core import mail
877 from django.test import TestCase
879 class EmailTest(TestCase):
880 def test_send_email(self):
882 mail.send_mail('Subject here', 'Here is the message.',
883 'from@example.com', ['to@example.com'],
886 # Test that one message has been sent.
887 self.assertEqual(len(mail.outbox), 1)
889 # Verify that the subject of the first message is correct.
890 self.assertEqual(mail.outbox[0].subject, 'Subject here')
892 As noted `previously`_, the test outbox is emptied at the start of every
893 test in a Django ``TestCase``. To empty the outbox manually, assign the
894 empty list to ``mail.outbox``::
896 from django.core import mail
898 # Empty the test outbox
901 .. _`Django's e-mail functionality`: ../email/
902 .. _`SMTPConnection`: ../email/#the-emailmessage-and-smtpconnection-classes
903 .. _`EmailMessage`: ../email/#the-emailmessage-and-smtpconnection-classes
904 .. _`previously`: #emptying-the-test-outbox
906 Using different testing frameworks
907 ==================================
909 Clearly, ``doctest`` and ``unittest`` are not the only Python testing
910 frameworks. While Django doesn't provide explicit support for alternative
911 frameworks, it does provide a way to invoke tests constructed for an
912 alternative framework as if they were normal Django tests.
914 When you run ``./manage.py test``, Django looks at the ``TEST_RUNNER``
915 setting to determine what to do. By default, ``TEST_RUNNER`` points to
916 ``'django.test.simple.run_tests'``. This method defines the default Django
917 testing behavior. This behavior involves:
919 #. Performing global pre-test setup.
921 #. Creating the test database.
923 #. Running ``syncdb`` to install models and initial data into the test
926 #. Looking for unit tests and doctests in the ``models.py`` and
927 ``tests.py`` files in each installed application.
929 #. Running the unit tests and doctests that are found.
931 #. Destroying the test database.
933 #. Performing global post-test teardown.
935 If you define your own test runner method and point ``TEST_RUNNER`` at that
936 method, Django will execute your test runner whenever you run
937 ``./manage.py test``. In this way, it is possible to use any test framework
938 that can be executed from Python code.
940 Defining a test runner
941 ----------------------
943 **New in Django development version**
945 By convention, a test runner should be called ``run_tests``. The only strict
946 requirement is that it has the same arguments as the Django test runner:
948 ``run_tests(test_labels, verbosity=1, interactive=True, extra_tests=[])``
950 ``test_labels`` is a list of strings describing the tests to be run. A test
951 label can take one of three forms:
953 * ``app.TestCase.test_method`` -- Run a single test method in a test case.
954 * ``app.TestCase`` -- Run all the test methods in a test case.
955 * ``app`` -- Search for and run all tests in the named application.
957 If ``test_labels`` has a value of ``None``, the test runner should run
958 search for tests in all the applications in ``INSTALLED_APPS``.
960 ``verbosity`` determines the amount of notification and debug information
961 that will be printed to the console; ``0`` is no output, ``1`` is normal
962 output, and ``2`` is verbose output.
964 If ``interactive`` is ``True``, the test suite has permission to ask the
965 user for instructions when the test suite is executed. An example of this
966 behavior would be asking for permission to delete an existing test
967 database. If ``interactive`` is ``False``, the test suite must be able to
968 run without any manual intervention.
970 ``extra_tests`` is a list of extra ``TestCase`` instances to add to the
971 suite that is executed by the test runner. These extra tests are run
972 in addition to those discovered in the modules listed in ``module_list``.
974 This method should return the number of tests that failed.
979 To assist in the creation of your own test runner, Django provides
980 a number of utility methods in the ``django.test.utils`` module.
982 ``setup_test_environment()``
983 Performs any global pre-test setup, such as the installing the
984 instrumentation of the template rendering system and setting up
985 the dummy ``SMTPConnection``.
987 ``teardown_test_environment()``
988 Performs any global post-test teardown, such as removing the
989 black magic hooks into the template system and restoring normal e-mail
992 ``create_test_db(verbosity=1, autoclobber=False)``
993 Creates a new test database and runs ``syncdb`` against it.
995 ``verbosity`` has the same behavior as in ``run_tests()``.
997 ``autoclobber`` describes the behavior that will occur if a database with
998 the same name as the test database is discovered:
1000 * If ``autoclobber`` is ``False``, the user will be asked to approve
1001 destroying the existing database. ``sys.exit`` is called if the user
1004 * If autoclobber is ``True``, the database will be destroyed without
1005 consulting the user.
1007 ``create_test_db()`` has the side effect of modifying
1008 ``settings.DATABASE_NAME`` to match the name of the test database.
1010 New in the Django development version, this function returns the name of
1011 the test database that it created.
1013 ``destroy_test_db(old_database_name, verbosity=1)``
1014 Destroys the database whose name is in the ``DATABASE_NAME`` setting
1015 and restores the value of ``DATABASE_NAME`` to the provided name.
1017 ``verbosity`` has the same behavior as in ``run_tests()``.