Writing and running tests

See also

The testing tutorial, the testing toolsreference, and the advanced testing topics.

This document is split into two primary sections. First, we explain how to writetests with Django. Then, we explain how to run them.

Writing tests

Django’s unit tests use a Python standard library module: unittest. Thismodule defines tests using a class-based approach.

Here is an example which subclasses from django.test.TestCase,which is a subclass of unittest.TestCase that runs each test inside atransaction to provide isolation:

  1. from django.test import TestCase
  2. from myapp.models import Animal
  3.  
  4. class AnimalTestCase(TestCase):
  5.     def setUp(self):
  6.         Animal.objects.create(name="lion", sound="roar")
  7.         Animal.objects.create(name="cat", sound="meow")
  8.  
  9.     def test_animals_can_speak(self):
  10.         """Animals that can speak are correctly identified"""
  11.         lion = Animal.objects.get(name="lion")
  12.         cat = Animal.objects.get(name="cat")
  13.         self.assertEqual(lion.speak(), 'The lion says "roar"')
  14.         self.assertEqual(cat.speak(), 'The cat says "meow"')

When you run your tests, the default behavior of thetest utility is to find all the test cases (that is, subclasses ofunittest.TestCase) in any file whose name begins with test,automatically build a test suite out of those test cases, and run that suite.

For more details about unittest, see the Python documentation.

Where should the tests live?

The default startapp template creates a tests.py file in thenew application. This might be fine if you only have a few tests, but asyour test suite grows you’ll likely want to restructure it into a testspackage so you can split your tests into different submodules such astest_models.py, test_views.py, test_forms.py, etc. Feel free topick whatever organizational scheme you like.

See also Using the Django test runner to test reusable applications.

Warning

If your tests rely on database access such as creating or querying models,be sure to create your test classes as subclasses ofdjango.test.TestCase rather than unittest.TestCase.

Using unittest.TestCase avoids the cost of running each test in atransaction and flushing the database, but if your tests interact withthe database their behavior will vary based on the order that the testrunner executes them. This can lead to unit tests that pass when run inisolation but fail when run in a suite.

Running tests

Once you’ve written tests, run them using the test command ofyour project’s manage.py utility:

  1. $ ./manage.py test

Test discovery is based on the unittest module’s built-in testdiscovery. By default, this will discover tests inany file named “test*.py” under the current working directory.

You can specify particular tests to run by supplying any number of “testlabels” to ./manage.py test. Each test label can be a full Python dottedpath to a package, module, TestCase subclass, or test method. For instance:

  1. # Run all the tests in the animals.tests module
  2. $ ./manage.py test animals.tests
  3.  
  4. # Run all the tests found within the 'animals' package
  5. $ ./manage.py test animals
  6.  
  7. # Run just one test case
  8. $ ./manage.py test animals.tests.AnimalTestCase
  9.  
  10. # Run just one test method
  11. $ ./manage.py test animals.tests.AnimalTestCase.test_animals_can_speak

You can also provide a path to a directory to discover tests below thatdirectory:

  1. $ ./manage.py test animals/

You can specify a custom filename pattern match using the -p (or—pattern) option, if your test files are named differently from thetest*.py pattern:

  1. $ ./manage.py test --pattern="tests_*.py"

If you press Ctrl-C while the tests are running, the test runner willwait for the currently running test to complete and then exit gracefully.During a graceful exit the test runner will output details of any testfailures, report on how many tests were run and how many errors and failureswere encountered, and destroy any test databases as usual. Thus pressingCtrl-C can be very useful if you forget to pass the —failfast option, notice that some tests are unexpectedly failing andwant to get details on the failures without waiting for the full test run tocomplete.

If you do not want to wait for the currently running test to finish, youcan press Ctrl-C a second time and the test run will halt immediately,but not gracefully. No details of the tests run before the interruption willbe reported, and any test databases created by the run will not be destroyed.

Test with warnings enabled

It’s a good idea to run your tests with Python warnings enabled:python -Wa manage.py test. The -Wa flag tells Python todisplay deprecation warnings. Django, like many other Python libraries,uses these warnings to flag when features are going away. It also mightflag areas in your code that aren’t strictly wrong but could benefitfrom a better implementation.

The test database

Tests that require a database (namely, model tests) will not use your “real”(production) database. Separate, blank databases are created for the tests.

Regardless of whether the tests pass or fail, the test databases are destroyedwhen all the tests have been executed.

You can prevent the test databases from being destroyed by using thetest —keepdb option. This will preserve the test database betweenruns. If the database does not exist, it will first be created. Any migrationswill also be applied in order to keep it up to date.

As described in the previous section, if a test run is forcefully interrupted,the test database may not be destroyed. On the next run, you’ll be askedwhether you want to reuse or destroy the database. Use the test—noinput option to suppress that prompt and automatically destroy thedatabase. This can be useful when running tests on a continuous integrationserver where tests may be interrupted by a timeout, for example.

The default test database names are created by prepending test_ to thevalue of each NAME in DATABASES. When using SQLite, thetests will use an in-memory database by default (i.e., the database will becreated in memory, bypassing the filesystem entirely!). The TEST dictionary in DATABASES offers a number of settingsto configure your test database. For example, if you want to use a differentdatabase name, specify NAME in the TEST dictionary for any given database in DATABASES.

On PostgreSQL, USER will also need read access to the built-inpostgres database.

Aside from using a separate database, the test runner will otherwiseuse all of the same database settings you have in your settings file:ENGINE, USER, HOST, etc. Thetest database is created by the user specified by USER, so you’llneed to make sure that the given user account has sufficient privileges tocreate a new database on the system.

For fine-grained control over the character encoding of your testdatabase, use the CHARSET TEST option. If you’re usingMySQL, you can also use the COLLATION option tocontrol the particular collation used by the test database. See thesettings documentation for details of theseand other advanced settings.

If using an SQLite in-memory database with SQLite, shared cache is enabled, so you can write testswith ability to share the database between threads.

Finding data from your production database when running tests?

If your code attempts to access the database when its modules are compiled,this will occur before the test database is set up, with potentiallyunexpected results. For example, if you have a database query inmodule-level code and a real database exists, production data could polluteyour tests. It is a bad idea to have such import-time database queries inyour code anyway - rewrite your code so that it doesn’t do this.

This also applies to customized implementations ofready().

See also

The advanced multi-db testing topics.

Order in which tests are executed

In order to guarantee that all TestCase code starts with a clean database,the Django test runner reorders tests in the following way:

  • All TestCase subclasses are run first.
  • Then, all other Django-based tests (test cases based onSimpleTestCase, includingTransactionTestCase) are run with no particularordering guaranteed nor enforced among them.
  • Then any other unittest.TestCase tests (including doctests) that mayalter the database without restoring it to its original state are run.

Note

The new ordering of tests may reveal unexpected dependencies on test caseordering. This is the case with doctests that relied on state left in thedatabase by a given TransactionTestCase test, theymust be updated to be able to run independently.

You may reverse the execution order inside groups using the test—reverse option. This can help with ensuring your tests are independent fromeach other.

Rollback emulation

Any initial data loaded in migrations will only be available in TestCasetests and not in TransactionTestCase tests, and additionally only onbackends where transactions are supported (the most important exception beingMyISAM). This is also true for tests which rely on TransactionTestCasesuch as LiveServerTestCase andStaticLiveServerTestCase.

Django can reload that data for you on a per-testcase basis bysetting the serialized_rollback option to True in the body of theTestCase or TransactionTestCase, but note that this will slow downthat test suite by approximately 3x.

Third-party apps or those developing against MyISAM will need to set this;in general, however, you should be developing your own projects against atransactional database and be using TestCase for most tests, and thusnot need this setting.

The initial serialization is usually very quick, but if you wish to excludesome apps from this process (and speed up test runs slightly), you may addthose apps to TEST_NON_SERIALIZED_APPS.

To prevent serialized data from being loaded twice, settingserialized_rollback=True disables thepost_migrate signal when flushing the testdatabase.

Other test conditions

Regardless of the value of the DEBUG setting in your configurationfile, all Django tests run with DEBUG=False. This is to ensure thatthe observed output of your code matches what will be seen in a productionsetting.

Caches are not cleared after each test, and running “manage.py test fooapp” caninsert data from the tests into the cache of a live system if you run yourtests in production because, unlike databases, a separate “test cache” is notused. This behavior may change in the future.

Understanding the test output

When you run your tests, you’ll see a number of messages as the test runnerprepares itself. You can control the level of detail of these messages with theverbosity option on the command line:

  1. Creating test database...
  2. Creating table myapp_animal
  3. Creating table myapp_mineral

This tells you that the test runner is creating a test database, as describedin the previous section.

Once the test database has been created, Django will run your tests.If everything goes well, you’ll see something like this:

  1. ----------------------------------------------------------------------
  2. Ran 22 tests in 0.221s
  3.  
  4. OK

If there are test failures, however, you’ll see full details about which testsfailed:

  1. ======================================================================
  2. FAIL: test_was_published_recently_with_future_poll (polls.tests.PollMethodTests)
  3. ----------------------------------------------------------------------
  4. Traceback (most recent call last):
  5.   File "/dev/mysite/polls/tests.py", line 16, in test_was_published_recently_with_future_poll
  6.     self.assertIs(future_poll.was_published_recently(), False)
  7. AssertionError: True is not False
  8.  
  9. ----------------------------------------------------------------------
  10. Ran 1 test in 0.003s
  11.  
  12. FAILED (failures=1)

A full explanation of this error output is beyond the scope of this document,but it’s pretty intuitive. You can consult the documentation of Python’sunittest library for details.

Note that the return code for the test-runner script is 1 for any number offailed and erroneous tests. If all the tests pass, the return code is 0. Thisfeature is useful if you’re using the test-runner script in a shell script andneed to test for success or failure at that level.

Speeding up the tests

Running tests in parallel

As long as your tests are properly isolated, you can run them in parallel togain a speed up on multi-core hardware. See test —parallel.

Password hashing

The default password hasher is rather slow by design. If you’re authenticatingmany users in your tests, you may want to use a custom settings file and setthe PASSWORD_HASHERS setting to a faster hashing algorithm:

  1. PASSWORD_HASHERS = [
  2.     'django.contrib.auth.hashers.MD5PasswordHasher',
  3. ]

Don’t forget to also include in PASSWORD_HASHERS any hashingalgorithm used in fixtures, if any.

Preserving the test database

The test —keepdb option preserves the test database between testruns. It skips the create and destroy actions which can greatly decrease thetime to run tests.