1 ===========================

     2 Testing Django applications

     3 ===========================

     4 

     5 .. module:: django.test

     6    :synopsis: Testing tools for Django applications.

     7 

     8 Automated testing is an extremely useful bug-killing tool for the modern

     9 Web developer. You can use a collection of tests -- a **test suite** -- to

    10 solve, or avoid, a number of problems:

    11 

    12     * When you're writing new code, you can use tests to validate your code

    13       works as expected.

    14 

    15     * When you're refactoring or modifying old code, you can use tests to

    16       ensure your changes haven't affected your application's behavior

    17       unexpectedly.

    18 

    19 Testing a Web application is a complex task, because a Web application is made

    20 of several layers of logic -- from HTTP-level request handling, to form

    21 validation and processing, to template rendering. With Django's test-execution

    22 framework and assorted utilities, you can simulate requests, insert test data,

    23 inspect your application's output and generally verify your code is doing what

    24 it should be doing.

    25 

    26 The best part is, it's really easy.

    27 

    28 This document is split into two primary sections. First, we explain how to

    29 write tests with Django. Then, we explain how to run them.

    30 

    31 Writing tests

    32 =============

    33 

    34 There are two primary ways to write tests with Django, corresponding to the

    35 two test frameworks that ship in the Python standard library. The two

    36 frameworks are:

    37 

    38     * **Doctests** -- tests that are embedded in your functions' docstrings and

    39       are written in a way that emulates a session of the Python interactive

    40       interpreter. For example::

    41 

    42           def my_func(a_list, idx):

    43               """

    44               >>> a = ['larry', 'curly', 'moe']

    45               >>> my_func(a, 0)

    46               'larry'

    47               >>> my_func(a, 1)

    48               'curly'

    49               """

    50               return a_list[idx]

    51 

    52     * **Unit tests** -- tests that are expressed as methods on a Python class

    53       that subclasses ``unittest.TestCase``. For example::

    54 

    55           import unittest

    56 

    57           class MyFuncTestCase(unittest.TestCase):

    58               def testBasic(self):

    59                   a = ['larry', 'curly', 'moe']

    60                   self.assertEquals(my_func(a, 0), 'larry')

    61                   self.assertEquals(my_func(a, 1), 'curly')

    62 

    63 You can choose the test framework you like, depending on which syntax you

    64 prefer, or you can mix and match, using one framework for some of your code and

    65 the other framework for other code. You can also use any *other* Python test

    66 frameworks, as we'll explain in a bit.

    67 

    68 Writing doctests

    69 ----------------

    70 

    71 Doctests use Python's standard doctest_ module, which searches your docstrings

    72 for statements that resemble a session of the Python interactive interpreter.

    73 A full explanation of how doctest works is out of the scope of this document;

    74 read Python's official documentation for the details.

    75 

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

    77 

    78     A good explanation of docstrings (and some guidelines for using them

    79     effectively) can be found in :pep:`257`:

    80 

    81         A docstring is a string literal that occurs as the first statement in

    82         a module, function, class, or method definition.  Such a docstring

    83         becomes the ``__doc__`` special attribute of that object.

    84 

    85     For example, this function has a docstring that describes what it does::

    86 

    87         def add_two(num):

    88           "Return the result of adding two to the provided number."

    89            return num + 2

    90 

    91     Because tests often make great documentation, putting tests directly in

    92     your docstrings is an effective way to document *and* test your code.

    93 

    94 For a given Django application, the test runner looks for doctests in two

    95 places:

    96 

    97     * The ``models.py`` file. You can define module-level doctests and/or a

    98       doctest for individual models. It's common practice to put

    99       application-level doctests in the module docstring and model-level

   100       doctests in the model docstrings.

   101 

   102     * A file called ``tests.py`` in the application directory -- i.e., the

   103       directory that holds ``models.py``. This file is a hook for any and all

   104       doctests you want to write that aren't necessarily related to models.

   105 

   106 Here is an example model doctest::

   107 

   108     # models.py

   109 

   110     from django.db import models

   111 

   112     class Animal(models.Model):

   113         """

   114         An animal that knows how to make noise

   115 

   116         # Create some animals

   117         >>> lion = Animal.objects.create(name="lion", sound="roar")

   118         >>> cat = Animal.objects.create(name="cat", sound="meow")

   119 

   120         # Make 'em speak

   121         >>> lion.speak()

   122         'The lion says "roar"'

   123         >>> cat.speak()

   124         'The cat says "meow"'

   125         """

   126         name = models.CharField(max_length=20)

   127         sound = models.CharField(max_length=20)

   128 

   129         def speak(self):

   130             return 'The %s says "%s"' % (self.name, self.sound)

   131 

   132 When you :ref:`run your tests <running-tests>`, the test runner will find this

   133 docstring, notice that portions of it look like an interactive Python session,

   134 and execute those lines while checking that the results match.

   135 

   136 In the case of model tests, note that the test runner takes care of creating

   137 its own test database. That is, any test that accesses a database -- by

   138 creating and saving model instances, for example -- will not affect your

   139 production database. However, the database is not refreshed between doctests,

   140 so if your doctest requires a certain state you should consider flushing the

   141 database or loading a fixture. (See the section on fixtures, below, for more

   142 on this.) Note that to use this feature, the database user Django is connecting

   143 as must have ``CREATE DATABASE`` rights.

   144 

   145 For more details about how doctest works, see the `standard library

   146 documentation for doctest`_.

   147 

   148 .. _doctest: http://docs.python.org/library/doctest.html

   149 .. _standard library documentation for doctest: doctest_

   150 

   151 Writing unit tests

   152 ------------------

   153 

   154 Like doctests, Django's unit tests use a standard library module: unittest_.

   155 This module uses a different way of defining tests, taking a class-based

   156 approach.

   157 

   158 As with doctests, for a given Django application, the test runner looks for

   159 unit tests in two places:

   160 

   161     * The ``models.py`` file. The test runner looks for any subclass of

   162       ``unittest.TestCase`` in this module.

   163 

   164     * A file called ``tests.py`` in the application directory -- i.e., the

   165       directory that holds ``models.py``. Again, the test runner looks for any

   166       subclass of ``unittest.TestCase`` in this module.

   167 

   168 This example ``unittest.TestCase`` subclass is equivalent to the example given

   169 in the doctest section above::

   170 

   171     import unittest

   172     from myapp.models import Animal

   173 

   174     class AnimalTestCase(unittest.TestCase):

   175         def setUp(self):

   176             self.lion = Animal.objects.create(name="lion", sound="roar")

   177             self.cat = Animal.objects.create(name="cat", sound="meow")

   178 

   179         def testSpeaking(self):

   180             self.assertEquals(self.lion.speak(), 'The lion says "roar"')

   181             self.assertEquals(self.cat.speak(), 'The cat says "meow"')

   182 

   183 When you :ref:`run your tests <running-tests>`, the default behavior of the

   184 test utility is to find all the test cases (that is, subclasses of

   185 ``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a

   186 test suite out of those test cases, and run that suite.

   187 

   188 There is a second way to define the test suite for a module: if you define a

   189 function called ``suite()`` in either ``models.py`` or ``tests.py``, the

   190 Django test runner will use that function to construct the test suite for that

   191 module. This follows the `suggested organization`_ for unit tests. See the

   192 Python documentation for more details on how to construct a complex test

   193 suite.

   194 

   195 For more details about ``unittest``, see the `standard library unittest

   196 documentation`_.

   197 

   198 .. _unittest: http://docs.python.org/library/unittest.html

   199 .. _standard library unittest documentation: unittest_

   200 .. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests

   201 

   202 Which should I use?

   203 -------------------

   204 

   205 Because Django supports both of the standard Python test frameworks, it's up to

   206 you and your tastes to decide which one to use. You can even decide to use

   207 *both*.

   208 

   209 For developers new to testing, however, this choice can seem confusing. Here,

   210 then, are a few key differences to help you decide which approach is right for

   211 you:

   212 

   213     * If you've been using Python for a while, ``doctest`` will probably feel

   214       more "pythonic". It's designed to make writing tests as easy as possible,

   215       so it requires no overhead of writing classes or methods. You simply put

   216       tests in docstrings. This has the added advantage of serving as

   217       documentation (and correct documentation, at that!).

   218 

   219       If you're just getting started with testing, using doctests will probably

   220       get you started faster.

   221 

   222     * The ``unittest`` framework will probably feel very familiar to developers

   223       coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll

   224       feel at home with this method if you've used JUnit or any test framework

   225       inspired by JUnit.

   226 

   227     * If you need to write a bunch of tests that share similar code, then

   228       you'll appreciate the ``unittest`` framework's organization around

   229       classes and methods. This makes it easy to abstract common tasks into

   230       common methods. The framework also supports explicit setup and/or cleanup

   231       routines, which give you a high level of control over the environment

   232       in which your test cases are run.

   233 

   234 Again, remember that you can use both systems side-by-side (even in the same

   235 app). In the end, most projects will eventually end up using both. Each shines

   236 in different circumstances.

   237 

   238 .. _running-tests:

   239 

   240 Running tests

   241 =============

   242 

   243 Once you've written tests, run them using the :djadmin:`test` command of

   244 your project's ``manage.py`` utility::

   245 

   246     $ ./manage.py test

   247 

   248 By default, this will run every test in every application in

   249 :setting:`INSTALLED_APPS`. If you only want to run tests for a particular

   250 application, add the application name to the command line. For example, if your

   251 :setting:`INSTALLED_APPS` contains ``'myproject.polls'`` and

   252 ``'myproject.animals'``, you can run the ``myproject.animals`` unit tests alone

   253 with this command::

   254 

   255     $ ./manage.py test animals

   256 

   257 Note that we used ``animals``, not ``myproject.animals``.

   258 

   259 .. versionadded:: 1.0

   260    You can now choose which test to run.

   261 

   262 You can be even *more* specific by naming an individual test case. To

   263 run a single test case in an application (for example, the

   264 ``AnimalTestCase`` described in the "Writing unit tests" section), add

   265 the name of the test case to the label on the command line::

   266 

   267     $ ./manage.py test animals.AnimalTestCase

   268 

   269 And it gets even more granular than that! To run a *single* test

   270 method inside a test case, add the name of the test method to the

   271 label::

   272 

   273     $ ./manage.py test animals.AnimalTestCase.testFluffyAnimals

   274 

   275 .. versionadded:: 1.2

   276    The ability to select individual doctests was added.

   277 

   278 You can use the same rules if you're using doctests. Django will use the

   279 test label as a path to the test method or class that you want to run.

   280 If your ``models.py`` or ``tests.py`` has a function with a doctest, or

   281 class with a class-level doctest, you can invoke that test by appending the

   282 name of the test method or class to the label::

   283 

   284     $ ./manage.py test animals.classify

   285 

   286 If you want to run the doctest for a specific method in a class, add the

   287 name of the method to the label::

   288 

   289     $ ./manage.py test animals.Classifier.run

   290 

   291 If you're using a ``__test__`` dictionary to specify doctests for a

   292 module, Django will use the label as a key in the ``__test__`` dictionary

   293 for defined in ``models.py`` and ``tests.py``.

   294 

   295 .. versionadded:: 1.2

   296    You can now trigger a graceful exit from a test run by pressing ``Ctrl-C``.

   297 

   298 If you press ``Ctrl-C`` while the tests are running, the test runner will

   299 wait for the currently running test to complete and then exit gracefully.

   300 During a graceful exit the test runner will output details of any test

   301 failures, report on how many tests were run and how many errors and failures

   302 were encountered, and destroy any test databases as usual. Thus pressing

   303 ``Ctrl-C`` can be very useful if you forget to pass the :djadminopt:`--failfast`

   304 option, notice that some tests are unexpectedly failing, and want to get details

   305 on the failures without waiting for the full test run to complete.

   306 

   307 If you do not want to wait for the currently running test to finish, you

   308 can press ``Ctrl-C`` a second time and the test run will halt immediately,

   309 but not gracefully. No details of the tests run before the interruption will

   310 be reported, and any test databases created by the run will not be destroyed.

   311 

   312 .. admonition:: Test with warnings enabled

   313 

   314     It is a good idea to run your tests with ``python -Wall manage.py

   315     test``. This will allow you to catch any deprecation warnings that

   316     might be in your code. Django (as well as many other libraries) use

   317     warnings to flag when features are deprecated. It can also flag

   318     areas in your code that are not strictly wrong, but may benefit

   319     from a better implementation.

   320 

   321 Running tests outside the test runner

   322 -------------------------------------

   323 

   324 If you want to run tests outside of ``./manage.py test`` -- for example,

   325 from a shell prompt -- you will need to set up the test

   326 environment first. Django provides a convenience method to do this::

   327 

   328     >>> from django.test.utils import setup_test_environment

   329     >>> setup_test_environment()

   330 

   331 This convenience method sets up the test database, and puts other

   332 Django features into modes that allow for repeatable testing.

   333 

   334 The call to :meth:`~django.test.utils.setup_test_environment` is made

   335 automatically as part of the setup of `./manage.py test`. You only

   336 need to manually invoke this method if you're not using running your

   337 tests via Django's test runner.

   338 

   339 The test database

   340 -----------------

   341 

   342 Tests that require a database (namely, model tests) will not use your "real"

   343 (production) database. Separate, blank databases are created for the tests.

   344 

   345 Regardless of whether the tests pass or fail, the test databases are destroyed

   346 when all the tests have been executed.

   347 

   348 By default the test databases get their names by prepending ``test_``

   349 to the value of the :setting:`NAME` settings for the databases

   350 defined in :setting:`DATABASES`. When using the SQLite database engine

   351 the tests will by default use an in-memory database (i.e., the

   352 database will be created in memory, bypassing the filesystem

   353 entirely!). If you want to use a different database name, specify

   354 :setting:`TEST_NAME` in the dictionary for any given database in

   355 :setting:`DATABASES`.

   356 

   357 Aside from using a separate database, the test runner will otherwise

   358 use all of the same database settings you have in your settings file:

   359 :setting:`ENGINE`, :setting:`USER`, :setting:`HOST`, etc. The test

   360 database is created by the user specified by ``USER``, so you'll need

   361 to make sure that the given user account has sufficient privileges to

   362 create a new database on the system.

   363 

   364 .. versionadded:: 1.0

   365 

   366 For fine-grained control over the character encoding of your test

   367 database, use the :setting:`TEST_CHARSET` option. If you're using

   368 MySQL, you can also use the :setting:`TEST_COLLATION` option to

   369 control the particular collation used by the test database. See the

   370 :doc:`settings documentation </ref/settings>` for details of these

   371 advanced settings.

   372 

   373 .. _topics-testing-masterslave:

   374 

   375 Testing master/slave configurations

   376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   377 

   378 .. versionadded:: 1.2

   379 

   380 If you're testing a multiple database configuration with master/slave

   381 replication, this strategy of creating test databases poses a problem.

   382 When the test databases are created, there won't be any replication,

   383 and as a result, data created on the master won't be seen on the

   384 slave.

   385 

   386 To compensate for this, Django allows you to define that a database is

   387 a *test mirror*. Consider the following (simplified) example database

   388 configuration::

   389 

   390     DATABASES = {

   391         'default': {

   392             'ENGINE': 'django.db.backends.mysql',

   393             'NAME': 'myproject',

   394             'HOST': 'dbmaster',

   395              # ... plus some other settings

   396         },

   397         'slave': {

   398             'ENGINE': 'django.db.backends.mysql',

   399             'NAME': 'myproject',

   400             'HOST': 'dbslave',

   401             'TEST_MIRROR': 'default'

   402             # ... plus some other settings

   403         }

   404     }

   405 

   406 In this setup, we have two database servers: ``dbmaster``, described

   407 by the database alias ``default``, and ``dbslave`` described by the

   408 alias ``slave``. As you might expect, ``dbslave`` has been configured

   409 by the database administrator as a read slave of ``dbmaster``, so in

   410 normal activity, any write to ``default`` will appear on ``slave``.

   411 

   412 If Django created two independent test databases, this would break any

   413 tests that expected replication to occur. However, the ``slave``

   414 database has been configured as a test mirror (using the

   415 :setting:`TEST_MIRROR` setting), indicating that under testing,

   416 ``slave`` should be treated as a mirror of ``default``.

   417 

   418 When the test environment is configured, a test version of ``slave``

   419 will *not* be created. Instead the connection to ``slave``

   420 will be redirected to point at ``default``. As a result, writes to

   421 ``default`` will appear on ``slave`` -- but because they are actually

   422 the same database, not because there is data replication between the

   423 two databases.

   424 

   425 .. _topics-testing-creation-dependencies:

   426 

   427 Controlling creation order for test databases

   428 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   429 

   430 .. versionadded:: 1.2.4

   431 

   432 By default, Django will always create the ``default`` database first.

   433 However, no guarantees are made on the creation order of any other

   434 databases in your test setup.

   435 

   436 If your database configuration requires a specific creation order, you

   437 can specify the dependencies that exist using the

   438 :setting:`TEST_DEPENDENCIES` setting. Consider the following

   439 (simplified) example database configuration::

   440 

   441     DATABASES = {

   442         'default': {

   443              # ... db settings

   444              'TEST_DEPENDENCIES': ['diamonds']

   445         },

   446         'diamonds': {

   447             # ... db settings

   448         },

   449         'clubs': {

   450             # ... db settings

   451             'TEST_DEPENDENCIES': ['diamonds']

   452         },

   453         'spades': {

   454             # ... db settings

   455             'TEST_DEPENDENCIES': ['diamonds','hearts']

   456         },

   457         'hearts': {

   458             # ... db settings

   459             'TEST_DEPENDENCIES': ['diamonds','clubs']

   460         }

   461     }

   462 

   463 Under this configuration, the ``diamonds`` database will be created first,

   464 as it is the only database alias without dependencies. The ``default``` and

   465 ``clubs`` alias will be created next (although the order of creation of this

   466 pair is not guaranteed); then ``hearts``; and finally ``spades``.

   467 

   468 If there are any circular dependencies in the

   469 :setting:`TEST_DEPENDENCIES` definition, an ``ImproperlyConfigured``

   470 exception will be raised.

   471 

   472 Other test conditions

   473 ---------------------

   474 

   475 Regardless of the value of the :setting:`DEBUG` setting in your configuration

   476 file, all Django tests run with :setting:`DEBUG`\=False. This is to ensure that

   477 the observed output of your code matches what will be seen in a production

   478 setting.

   479 

   480 Understanding the test output

   481 -----------------------------

   482 

   483 When you run your tests, you'll see a number of messages as the test runner

   484 prepares itself. You can control the level of detail of these messages with the

   485 ``verbosity`` option on the command line::

   486 

   487     Creating test database...

   488     Creating table myapp_animal

   489     Creating table myapp_mineral

   490     Loading 'initial_data' fixtures...

   491     No fixtures found.

   492 

   493 This tells you that the test runner is creating a test database, as described

   494 in the previous section.

   495 

   496 Once the test database has been created, Django will run your tests.

   497 If everything goes well, you'll see something like this::

   498 

   499     ----------------------------------------------------------------------

   500     Ran 22 tests in 0.221s

   501 

   502     OK

   503 

   504 If there are test failures, however, you'll see full details about which tests

   505 failed::

   506 

   507     ======================================================================

   508     FAIL: Doctest: ellington.core.throttle.models

   509     ----------------------------------------------------------------------

   510     Traceback (most recent call last):

   511       File "/dev/django/test/doctest.py", line 2153, in runTest

   512         raise self.failureException(self.format_failure(new.getvalue()))

   513     AssertionError: Failed doctest test for myapp.models

   514       File "/dev/myapp/models.py", line 0, in models

   515 

   516     ----------------------------------------------------------------------

   517     File "/dev/myapp/models.py", line 14, in myapp.models

   518     Failed example:

   519         throttle.check("actor A", "action one", limit=2, hours=1)

   520     Expected:

   521         True

   522     Got:

   523         False

   524 

   525     ----------------------------------------------------------------------

   526     Ran 2 tests in 0.048s

   527 

   528     FAILED (failures=1)

   529 

   530 A full explanation of this error output is beyond the scope of this document,

   531 but it's pretty intuitive. You can consult the documentation of Python's

   532 ``unittest`` library for details.

   533 

   534 Note that the return code for the test-runner script is the total number of

   535 failed and erroneous tests. If all the tests pass, the return code is 0. This

   536 feature is useful if you're using the test-runner script in a shell script and

   537 need to test for success or failure at that level.

   538 

   539 Testing tools

   540 =============

   541 

   542 Django provides a small set of tools that come in handy when writing tests.

   543 

   544 The test client

   545 ---------------

   546 

   547 .. module:: django.test.client

   548    :synopsis: Django's test client.

   549 

   550 The test client is a Python class that acts as a dummy Web browser, allowing

   551 you to test your views and interact with your Django-powered application

   552 programmatically.

   553 

   554 Some of the things you can do with the test client are:

   555 

   556     * Simulate GET and POST requests on a URL and observe the response --

   557       everything from low-level HTTP (result headers and status codes) to

   558       page content.

   559 

   560     * Test that the correct view is executed for a given URL.

   561 

   562     * Test that a given request is rendered by a given Django template, with

   563       a template context that contains certain values.

   564 

   565 Note that the test client is not intended to be a replacement for Twill_,

   566 Selenium_, or other "in-browser" frameworks. Django's test client has

   567 a different focus. In short:

   568 

   569     * Use Django's test client to establish that the correct view is being

   570       called and that the view is collecting the correct context data.

   571 

   572     * Use in-browser frameworks such as Twill and Selenium to test *rendered*

   573       HTML and the *behavior* of Web pages, namely JavaScript functionality.

   574 

   575 A comprehensive test suite should use a combination of both test types.

   576 

   577 .. _Twill: http://twill.idyll.org/

   578 .. _Selenium: http://seleniumhq.org/

   579 

   580 Overview and a quick example

   581 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   582 

   583 To use the test client, instantiate ``django.test.client.Client`` and retrieve

   584 Web pages::

   585 

   586     >>> from django.test.client import Client

   587     >>> c = Client()

   588     >>> response = c.post('/login/', {'username': 'john', 'password': 'smith'})

   589     >>> response.status_code

   590     200

   591     >>> response = c.get('/customer/details/')

   592     >>> response.content

   593     '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...'

   594 

   595 As this example suggests, you can instantiate ``Client`` from within a session

   596 of the Python interactive interpreter.

   597 

   598 Note a few important things about how the test client works:

   599 

   600     * The test client does *not* require the Web server to be running. In fact,

   601       it will run just fine with no Web server running at all! That's because

   602       it avoids the overhead of HTTP and deals directly with the Django

   603       framework. This helps make the unit tests run quickly.

   604 

   605     * When retrieving pages, remember to specify the *path* of the URL, not the

   606       whole domain. For example, this is correct::

   607 

   608           >>> c.get('/login/')

   609 

   610       This is incorrect::

   611 

   612           >>> c.get('http://www.example.com/login/')

   613 

   614       The test client is not capable of retrieving Web pages that are not

   615       powered by your Django project. If you need to retrieve other Web pages,

   616       use a Python standard library module such as urllib_ or urllib2_.

   617 

   618     * To resolve URLs, the test client uses whatever URLconf is pointed-to by

   619       your :setting:`ROOT_URLCONF` setting.

   620 

   621     * Although the above example would work in the Python interactive

   622       interpreter, some of the test client's functionality, notably the

   623       template-related functionality, is only available *while tests are

   624       running*.

   625 

   626       The reason for this is that Django's test runner performs a bit of black

   627       magic in order to determine which template was loaded by a given view.

   628       This black magic (essentially a patching of Django's template system in

   629       memory) only happens during test running.

   630 

   631     * By default, the test client will disable any CSRF checks

   632       performed by your site.

   633 

   634       .. versionadded:: 1.2.2

   635 

   636       If, for some reason, you *want* the test client to perform CSRF

   637       checks, you can create an instance of the test client that

   638       enforces CSRF checks. To do this, pass in the

   639       ``enforce_csrf_checks`` argument when you construct your

   640       client::

   641 

   642           >>> from django.test import Client

   643           >>> csrf_client = Client(enforce_csrf_checks=True)

   644 

   645 

   646 .. _urllib: http://docs.python.org/library/urllib.html

   647 .. _urllib2: http://docs.python.org/library/urllib2.html

   648 

   649 Making requests

   650 ~~~~~~~~~~~~~~~

   651 

   652 Use the ``django.test.client.Client`` class to make requests. It requires no

   653 arguments at time of construction:

   654 

   655 .. class:: Client()

   656 

   657     Once you have a ``Client`` instance, you can call any of the following

   658     methods:

   659 

   660     .. method:: Client.get(path, data={}, follow=False, **extra)

   661 

   662 

   663         Makes a GET request on the provided ``path`` and returns a ``Response``

   664         object, which is documented below.

   665 

   666         The key-value pairs in the ``data`` dictionary are used to create a GET

   667         data payload. For example::

   668 

   669             >>> c = Client()

   670             >>> c.get('/customers/details/', {'name': 'fred', 'age': 7})

   671 

   672         ...will result in the evaluation of a GET request equivalent to::

   673 

   674             /customers/details/?name=fred&age=7

   675 

   676         The ``extra`` keyword arguments parameter can be used to specify

   677         headers to be sent in the request. For example::

   678 

   679             >>> c = Client()

   680             >>> c.get('/customers/details/', {'name': 'fred', 'age': 7},

   681             ...       HTTP_X_REQUESTED_WITH='XMLHttpRequest')

   682 

   683         ...will send the HTTP header ``HTTP_X_REQUESTED_WITH`` to the

   684         details	view, which is a good way to test code paths that use the

   685         :meth:`django.http.HttpRequest.is_ajax()` method.

   686 

   687         .. versionadded:: 1.1

   688 

   689         If you already have the GET arguments in URL-encoded form, you can

   690         use that encoding instead of using the data argument. For example,

   691         the previous GET request could also be posed as::

   692 

   693         >>> c = Client()

   694         >>> c.get('/customers/details/?name=fred&age=7')

   695 

   696         If you provide a URL with both an encoded GET data and a data argument,

   697         the data argument will take precedence.

   698 

   699         If you set ``follow`` to ``True`` the client will follow any redirects

   700         and a ``redirect_chain`` attribute will be set in the response object

   701         containing tuples of the intermediate urls and status codes.

   702 

   703         If you had an url ``/redirect_me/`` that redirected to ``/next/``, that

   704         redirected to ``/final/``, this is what you'd see::

   705 

   706             >>> response = c.get('/redirect_me/', follow=True)

   707             >>> response.redirect_chain

   708             [(u'http://testserver/next/', 302), (u'http://testserver/final/', 302)]

   709 

   710     .. method:: Client.post(path, data={}, content_type=MULTIPART_CONTENT, follow=False, **extra)

   711 

   712         Makes a POST request on the provided ``path`` and returns a

   713         ``Response`` object, which is documented below.

   714 

   715         The key-value pairs in the ``data`` dictionary are used to submit POST

   716         data. For example::

   717 

   718             >>> c = Client()

   719             >>> c.post('/login/', {'name': 'fred', 'passwd': 'secret'})

   720 

   721         ...will result in the evaluation of a POST request to this URL::

   722 

   723             /login/

   724 

   725         ...with this POST data::

   726 

   727             name=fred&passwd=secret

   728 

   729         If you provide ``content_type`` (e.g., ``text/xml`` for an XML

   730         payload), the contents of ``data`` will be sent as-is in the POST

   731         request, using ``content_type`` in the HTTP ``Content-Type`` header.

   732 

   733         If you don't provide a value for ``content_type``, the values in

   734         ``data`` will be transmitted with a content type of

   735         ``multipart/form-data``. In this case, the key-value pairs in ``data``

   736         will be encoded as a multipart message and used to create the POST data

   737         payload.

   738 

   739         To submit multiple values for a given key -- for example, to specify

   740         the selections for a ``<select multiple>`` -- provide the values as a

   741         list or tuple for the required key. For example, this value of ``data``

   742         would submit three selected values for the field named ``choices``::

   743 

   744             {'choices': ('a', 'b', 'd')}

   745 

   746         Submitting files is a special case. To POST a file, you need only

   747         provide the file field name as a key, and a file handle to the file you

   748         wish to upload as a value. For example::

   749 

   750             >>> c = Client()

   751             >>> f = open('wishlist.doc')

   752             >>> c.post('/customers/wishes/', {'name': 'fred', 'attachment': f})

   753             >>> f.close()

   754 

   755         (The name ``attachment`` here is not relevant; use whatever name your

   756         file-processing code expects.)

   757 

   758         Note that if you wish to use the same file handle for multiple

   759         ``post()`` calls then you will need to manually reset the file

   760         pointer between posts. The easiest way to do this is to

   761         manually close the file after it has been provided to

   762         ``post()``, as demonstrated above.

   763 

   764         You should also ensure that the file is opened in a way that

   765         allows the data to be read. If your file contains binary data

   766         such as an image, this means you will need to open the file in

   767         ``rb`` (read binary) mode.

   768 

   769         The ``extra`` argument acts the same as for :meth:`Client.get`.

   770 

   771         .. versionchanged:: 1.1

   772 

   773         If the URL you request with a POST contains encoded parameters, these

   774         parameters will be made available in the request.GET data. For example,

   775         if you were to make the request::

   776 

   777         >>> c.post('/login/?visitor=true', {'name': 'fred', 'passwd': 'secret'})

   778 

   779         ... the view handling this request could interrogate request.POST

   780         to retrieve the username and password, and could interrogate request.GET

   781         to determine if the user was a visitor.

   782 

   783         If you set ``follow`` to ``True`` the client will follow any redirects

   784         and a ``redirect_chain`` attribute will be set in the response object

   785         containing tuples of the intermediate urls and status codes.

   786 

   787     .. method:: Client.head(path, data={}, follow=False, **extra)

   788 

   789         .. versionadded:: 1.1

   790 

   791         Makes a HEAD request on the provided ``path`` and returns a ``Response``

   792         object. Useful for testing RESTful interfaces. Acts just like

   793         :meth:`Client.get` except it does not return a message body.

   794 

   795         If you set ``follow`` to ``True`` the client will follow any redirects

   796         and a ``redirect_chain`` attribute will be set in the response object

   797         containing tuples of the intermediate urls and status codes.

   798 

   799     .. method:: Client.options(path, data={}, follow=False, **extra)

   800 

   801         .. versionadded:: 1.1

   802 

   803         Makes an OPTIONS request on the provided ``path`` and returns a

   804         ``Response`` object. Useful for testing RESTful interfaces.

   805 

   806         If you set ``follow`` to ``True`` the client will follow any redirects

   807         and a ``redirect_chain`` attribute will be set in the response object

   808         containing tuples of the intermediate urls and status codes.

   809 

   810         The ``extra`` argument acts the same as for :meth:`Client.get`.

   811 

   812     .. method:: Client.put(path, data={}, content_type=MULTIPART_CONTENT, follow=False, **extra)

   813 

   814         .. versionadded:: 1.1

   815 

   816         Makes a PUT request on the provided ``path`` and returns a

   817         ``Response`` object. Useful for testing RESTful interfaces. Acts just

   818         like :meth:`Client.post` except with the PUT request method.

   819 

   820         If you set ``follow`` to ``True`` the client will follow any redirects

   821         and a ``redirect_chain`` attribute will be set in the response object

   822         containing tuples of the intermediate urls and status codes.

   823 

   824     .. method:: Client.delete(path, follow=False, **extra)

   825 

   826         .. versionadded:: 1.1

   827 

   828         Makes an DELETE request on the provided ``path`` and returns a

   829         ``Response`` object. Useful for testing RESTful interfaces.

   830 

   831         If you set ``follow`` to ``True`` the client will follow any redirects

   832         and a ``redirect_chain`` attribute will be set in the response object

   833         containing tuples of the intermediate urls and status codes.

   834 

   835         The ``extra`` argument acts the same as for :meth:`Client.get`.

   836 

   837     .. method:: Client.login(**credentials)

   838 

   839         .. versionadded:: 1.0

   840 

   841         If your site uses Django's :doc:`authentication system</topics/auth>`

   842         and you deal with logging in users, you can use the test client's

   843         ``login()`` method to simulate the effect of a user logging into the

   844         site.

   845 

   846         After you call this method, the test client will have all the cookies

   847         and session data required to pass any login-based tests that may form

   848         part of a view.

   849 

   850         The format of the ``credentials`` argument depends on which

   851         :ref:`authentication backend <authentication-backends>` you're using

   852         (which is configured by your :setting:`AUTHENTICATION_BACKENDS`

   853         setting). If you're using the standard authentication backend provided

   854         by Django (``ModelBackend``), ``credentials`` should be the user's

   855         username and password, provided as keyword arguments::

   856 

   857             >>> c = Client()

   858             >>> c.login(username='fred', password='secret')

   859 

   860             # Now you can access a view that's only available to logged-in users.

   861 

   862         If you're using a different authentication backend, this method may

   863         require different credentials. It requires whichever credentials are

   864         required by your backend's ``authenticate()`` method.

   865 

   866         ``login()`` returns ``True`` if it the credentials were accepted and

   867         login was successful.

   868 

   869         Finally, you'll need to remember to create user accounts before you can

   870         use this method. As we explained above, the test runner is executed

   871         using a test database, which contains no users by default. As a result,

   872         user accounts that are valid on your production site will not work

   873         under test conditions. You'll need to create users as part of the test

   874         suite -- either manually (using the Django model API) or with a test

   875         fixture. Remember that if you want your test user to have a password,

   876         you can't set the user's password by setting the password attribute

   877         directly -- you must use the

   878         :meth:`~django.contrib.auth.models.User.set_password()` function to

   879         store a correctly hashed password. Alternatively, you can use the

   880         :meth:`~django.contrib.auth.models.UserManager.create_user` helper

   881         method to create a new user with a correctly hashed password.

   882 

   883     .. method:: Client.logout()

   884 

   885         .. versionadded:: 1.0

   886 

   887         If your site uses Django's :doc:`authentication system</topics/auth>`,

   888         the ``logout()`` method can be used to simulate the effect of a user

   889         logging out of your site.

   890 

   891         After you call this method, the test client will have all the cookies

   892         and session data cleared to defaults. Subsequent requests will appear

   893         to come from an AnonymousUser.

   894 

   895 Testing responses

   896 ~~~~~~~~~~~~~~~~~

   897 

   898 The ``get()`` and ``post()`` methods both return a ``Response`` object. This

   899 ``Response`` object is *not* the same as the ``HttpResponse`` object returned

   900 Django views; the test response object has some additional data useful for

   901 test code to verify.

   902 

   903 Specifically, a ``Response`` object has the following attributes:

   904 

   905 .. class:: Response()

   906 

   907     .. attribute:: client

   908 

   909         The test client that was used to make the request that resulted in the

   910         response.

   911 

   912     .. attribute:: content

   913 

   914         The body of the response, as a string. This is the final page content as

   915         rendered by the view, or any error message.

   916 

   917     .. attribute:: context

   918 

   919         The template ``Context`` instance that was used to render the template that

   920         produced the response content.

   921 

   922         If the rendered page used multiple templates, then ``context`` will be a

   923         list of ``Context`` objects, in the order in which they were rendered.

   924 

   925         .. versionadded:: 1.1

   926 

   927         Regardless of the number of templates used during rendering, you can

   928         retrieve context values using the ``[]`` operator. For example, the

   929         context variable ``name`` could be retrieved using::

   930 

   931             >>> response = client.get('/foo/')

   932             >>> response.context['name']

   933             'Arthur'

   934 

   935     .. attribute:: request

   936 

   937         The request data that stimulated the response.

   938 

   939     .. attribute:: status_code

   940 

   941         The HTTP status of the response, as an integer. See RFC2616_ for a full

   942         list of HTTP status codes.

   943 

   944     .. attribute:: template

   945 

   946         The ``Template`` instance that was used to render the final content. Use

   947         ``template.name`` to get the template's file name, if the template was

   948         loaded from a file. (The name is a string such as ``'admin/index.html'``.)

   949 

   950         If the rendered page used multiple templates -- e.g., using :ref:`template

   951         inheritance<template-inheritance>` -- then ``template`` will be a list of

   952         ``Template`` instances, in the order in which they were rendered.

   953 

   954 You can also use dictionary syntax on the response object to query the value

   955 of any settings in the HTTP headers. For example, you could determine the

   956 content type of a response using ``response['Content-Type']``.

   957 

   958 .. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

   959 

   960 Exceptions

   961 ~~~~~~~~~~

   962 

   963 If you point the test client at a view that raises an exception, that exception

   964 will be visible in the test case. You can then use a standard ``try...except``

   965 block or ``unittest.TestCase.assertRaises()`` to test for exceptions.

   966 

   967 The only exceptions that are not visible to the test client are ``Http404``,

   968 ``PermissionDenied`` and ``SystemExit``. Django catches these exceptions

   969 internally and converts them into the appropriate HTTP response codes. In these

   970 cases, you can check ``response.status_code`` in your test.

   971 

   972 Persistent state

   973 ~~~~~~~~~~~~~~~~

   974 

   975 The test client is stateful. If a response returns a cookie, then that cookie

   976 will be stored in the test client and sent with all subsequent ``get()`` and

   977 ``post()`` requests.

   978 

   979 Expiration policies for these cookies are not followed. If you want a cookie

   980 to expire, either delete it manually or create a new ``Client`` instance (which

   981 will effectively delete all cookies).

   982 

   983 A test client has two attributes that store persistent state information. You

   984 can access these properties as part of a test condition.

   985 

   986 .. attribute:: Client.cookies

   987 

   988     A Python ``SimpleCookie`` object, containing the current values of all the

   989     client cookies. See the `Cookie module documentation`_ for more.

   990 

   991 .. attribute:: Client.session

   992 

   993     A dictionary-like object containing session information. See the

   994     :doc:`session documentation</topics/http/sessions>` for full details.

   995 

   996     To modify the session and then save it, it must be stored in a variable

   997     first (because a new ``SessionStore`` is created every time this property

   998     is accessed)::

   999 

  1000         def test_something(self):

  1001             session = self.client.session

  1002             session['somekey'] = 'test'

  1003             session.save()

  1004 

  1005 .. _Cookie module documentation: http://docs.python.org/library/cookie.html

  1006 

  1007 Example

  1008 ~~~~~~~

  1009 

  1010 The following is a simple unit test using the test client::

  1011 

  1012     import unittest

  1013     from django.test.client import Client

  1014 

  1015     class SimpleTest(unittest.TestCase):

  1016         def setUp(self):

  1017             # Every test needs a client.

  1018             self.client = Client()

  1019 

  1020         def test_details(self):

  1021             # Issue a GET request.

  1022             response = self.client.get('/customer/details/')

  1023 

  1024             # Check that the response is 200 OK.

  1025             self.failUnlessEqual(response.status_code, 200)

  1026 

  1027             # Check that the rendered context contains 5 customers.

  1028             self.failUnlessEqual(len(response.context['customers']), 5)

  1029 

  1030 TestCase

  1031 --------

  1032 

  1033 .. currentmodule:: django.test

  1034 

  1035 Normal Python unit test classes extend a base class of ``unittest.TestCase``.

  1036 Django provides an extension of this base class:

  1037 

  1038 .. class:: TestCase()

  1039 

  1040 This class provides some additional capabilities that can be useful for testing

  1041 Web sites.

  1042 

  1043 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:

  1044 just change the base class of your test from ``unittest.TestCase`` to

  1045 ``django.test.TestCase``. All of the standard Python unit test functionality

  1046 will continue to be available, but it will be augmented with some useful

  1047 additions.

  1048 

  1049 .. versionadded:: 1.1

  1050 

  1051 .. class:: TransactionTestCase()

  1052 

  1053 Django ``TestCase`` classes make use of database transaction facilities, if

  1054 available, to speed up the process of resetting the database to a known state

  1055 at the beginning of each test. A consequence of this, however, is that the

  1056 effects of transaction commit and rollback cannot be tested by a Django

  1057 ``TestCase`` class. If your test requires testing of such transactional

  1058 behavior, you should use a Django ``TransactionTestCase``.

  1059 

  1060 ``TransactionTestCase`` and ``TestCase`` are identical except for the manner

  1061 in which the database is reset to a known state and the ability for test code

  1062 to test the effects of commit and rollback. A ``TransactionTestCase`` resets

  1063 the database before the test runs by truncating all tables and reloading

  1064 initial data. A ``TransactionTestCase`` may call commit and rollback and

  1065 observe the effects of these calls on the database.

  1066 

  1067 A ``TestCase``, on the other hand, does not truncate tables and reload initial

  1068 data at the beginning of a test. Instead, it encloses the test code in a

  1069 database transaction that is rolled back at the end of the test.  It also

  1070 prevents the code under test from issuing any commit or rollback operations

  1071 on the database, to ensure that the rollback at the end of the test restores

  1072 the database to its initial state. In order to guarantee that all ``TestCase``

  1073 code starts with a clean database, the Django test runner runs all ``TestCase``

  1074 tests first, before any other tests (e.g. doctests) that may alter the

  1075 database without restoring it to its original state.

  1076 

  1077 When running on a database that does not support rollback (e.g. MySQL with the

  1078 MyISAM storage engine), ``TestCase`` falls back to initializing the database

  1079 by truncating tables and reloading initial data.

  1080 

  1081 

  1082 .. note::

  1083     The ``TestCase`` use of rollback to un-do the effects of the test code

  1084     may reveal previously-undetected errors in test code.  For example,

  1085     test code that assumes primary keys values will be assigned starting at

  1086     one may find that assumption no longer holds true when rollbacks instead

  1087     of table truncation are being used to reset the database.  Similarly,

  1088     the reordering of tests so that all ``TestCase`` classes run first may

  1089     reveal unexpected dependencies on test case ordering.  In such cases a

  1090     quick fix is to switch the ``TestCase`` to a ``TransactionTestCase``.

  1091     A better long-term fix, that allows the test to take advantage of the

  1092     speed benefit of ``TestCase``, is to fix the underlying test problem.

  1093 

  1094 

  1095 Default test client

  1096 ~~~~~~~~~~~~~~~~~~~

  1097 

  1098 .. versionadded:: 1.0

  1099 

  1100 .. attribute:: TestCase.client

  1101 

  1102 Every test case in a ``django.test.TestCase`` instance has access to an

  1103 instance of a Django test client. This client can be accessed as

  1104 ``self.client``. This client is recreated for each test, so you don't have to

  1105 worry about state (such as cookies) carrying over from one test to another.

  1106 

  1107 This means, instead of instantiating a ``Client`` in each test::

  1108 

  1109     import unittest

  1110     from django.test.client import Client

  1111 

  1112     class SimpleTest(unittest.TestCase):

  1113         def test_details(self):

  1114             client = Client()

  1115             response = client.get('/customer/details/')

  1116             self.failUnlessEqual(response.status_code, 200)

  1117 

  1118         def test_index(self):

  1119             client = Client()

  1120             response = client.get('/customer/index/')

  1121             self.failUnlessEqual(response.status_code, 200)

  1122 

  1123 ...you can just refer to ``self.client``, like so::

  1124 

  1125     from django.test import TestCase

  1126 

  1127     class SimpleTest(TestCase):

  1128         def test_details(self):

  1129             response = self.client.get('/customer/details/')

  1130             self.failUnlessEqual(response.status_code, 200)

  1131 

  1132         def test_index(self):

  1133             response = self.client.get('/customer/index/')

  1134             self.failUnlessEqual(response.status_code, 200)

  1135 

  1136 .. _topics-testing-fixtures: