This document is split into two primary sections. First, we explain how to\nwrite tests with Django. Then, we explain how to run them.
\nDjango's unit tests use a Python standard library module: unittest. This\nmodule defines tests using a class-based approach.
Here is an example which subclasses from django.test.TestCase,\nwhich is a subclass of unittest.TestCase that runs each test inside a\ntransaction to provide isolation:
from django.test import TestCase\nfrom myapp.models import Animal\n\n\nclass AnimalTestCase(TestCase):\n def setUp(self):\n Animal.objects.create(name="lion", sound="roar")\n Animal.objects.create(name="cat", sound="meow")\n\n def test_animals_can_speak(self):\n """Animals that can speak are correctly identified"""\n lion = Animal.objects.get(name="lion")\n cat = Animal.objects.get(name="cat")\n self.assertEqual(lion.speak(), 'The lion says "roar"')\n self.assertEqual(cat.speak(), 'The cat says "meow"')\nWhen you run your tests, the default behavior of the\ntest utility is to find all the test case classes (that is, subclasses of\nunittest.TestCase) in any file whose name begins with test,\nautomatically build a test suite out of those test case classes, and run that\nsuite.
For more details about unittest, see the Python documentation.
Once you've written tests, run them using the test command of\nyour project's manage.py utility:
$ ./manage.py test\nTest discovery is based on the unittest module's built-in test\ndiscovery. By default, this will discover tests in\nany file named test*.py under the current working directory.
You can specify particular tests to run by supplying any number of "test\nlabels" to ./manage.py test. Each test label can be a full Python dotted\npath to a package, module, TestCase subclass, or test method. For instance:
# Run all the tests in the animals.tests module\n$ ./manage.py test animals.tests\n\n# Run all the tests found within the 'animals' package\n$ ./manage.py test animals\n\n# Run just one test case class\n$ ./manage.py test animals.tests.AnimalTestCase\n\n# Run just one test method\n$ ./manage.py test animals.tests.AnimalTestCase.test_animals_can_speak\nYou can also provide a path to a directory to discover tests below that\ndirectory:
\n$ ./manage.py test animals/\nYou can specify a custom filename pattern match using the -p (or\n--pattern) option, if your test files are named differently from the\ntest*.py pattern:
$ ./manage.py test --pattern="tests_*.py"\nIf you press Ctrl-C while the tests are running, the test runner will\nwait for the currently running test to complete and then exit gracefully.\nDuring a graceful exit the test runner will output details of any test\nfailures, report on how many tests were run and how many errors and failures\nwere encountered, and destroy any test databases as usual. Thus pressing\nCtrl-C can be very useful if you forget to pass the --failfast option, notice that some tests are unexpectedly failing and\nwant to get details on the failures without waiting for the full test run to\ncomplete.
If you do not want to wait for the currently running test to finish, you\ncan press Ctrl-C a second time and the test run will halt immediately,\nbut not gracefully. No details of the tests run before the interruption will\nbe reported, and any test databases created by the run will not be destroyed.
Tests that require a database (namely, model tests) will not use your "real"\n(production) database. Separate, blank databases are created for the tests.
\nRegardless of whether the tests pass or fail, the test databases are destroyed\nwhen all the tests have been executed.
\nYou can prevent the test databases from being destroyed by using the\ntest --keepdb option. This will preserve the test database between\nruns. If the database does not exist, it will first be created. Any migrations\nwill also be applied in order to keep it up to date.
As described in the previous section, if a test run is forcefully interrupted,\nthe test database may not be destroyed. On the next run, you'll be asked\nwhether you want to reuse or destroy the database. Use the test\n--noinput option to suppress that prompt and automatically destroy the\ndatabase. This can be useful when running tests on a continuous integration\nserver where tests may be interrupted by a timeout, for example.
The default test database names are created by prepending test_ to the\nvalue of each NAME in DATABASES. When using SQLite, the\ntests will use an in-memory database by default (i.e., the database will be\ncreated in memory, bypassing the filesystem entirely!). The TEST dictionary in DATABASES offers a number of settings\nto configure your test database. For example, if you want to use a different\ndatabase name, specify NAME in the TEST dictionary for any given database in DATABASES.
On PostgreSQL, USER will also need read access to the built-in\npostgres database.
Aside from using a separate database, the test runner will otherwise\nuse all of the same database settings you have in your settings file:\nENGINE, USER, HOST, etc. The\ntest database is created by the user specified by USER, so you'll\nneed to make sure that the given user account has sufficient privileges to\ncreate a new database on the system.
For fine-grained control over the character encoding of your test database, use\nthe CHARSET TEST option. If you're using MySQL, you\ncan also use the COLLATION option to control the\nparticular collation used by the test database. See the settings\ndocumentation for details of these and other advanced\nsettings.
If using an SQLite in-memory database with SQLite, shared cache is enabled, so you can write tests\nwith ability to share the database between threads.
\n\n\nIn order to guarantee that all TestCase code starts with a clean database,\nthe Django test runner reorders tests in the following way:
All TestCase subclasses are run first.
Then, all other Django-based tests (test case classes based on\nSimpleTestCase, including\nTransactionTestCase) are run with no particular\nordering guaranteed nor enforced among them.
Then any other unittest.TestCase tests (including doctests) that may\nalter the database without restoring it to its original state are run.
You may randomize and/or reverse the execution order inside groups using the\ntest --shuffle and --reverse options. This\ncan help with ensuring your tests are independent from each other.
Any initial data loaded in migrations will only be available in TestCase\ntests and not in TransactionTestCase tests, and additionally only on\nbackends where transactions are supported (the most important exception being\nMyISAM). This is also true for tests which rely on TransactionTestCase\nsuch as LiveServerTestCase and\nStaticLiveServerTestCase.
Django can reload that data for you on a per-testcase basis by\nsetting the serialized_rollback option to True in the body of the\nTestCase or TransactionTestCase, but note that this will slow down\nthat test suite by approximately 3x.
Third-party apps or those developing against MyISAM will need to set this;\nin general, however, you should be developing your own projects against a\ntransactional database and be using TestCase for most tests, and thus\nnot need this setting.
The initial serialization is usually very quick, but if you wish to exclude\nsome apps from this process (and speed up test runs slightly), you may add\nthose apps to TEST_NON_SERIALIZED_APPS.
To prevent serialized data from being loaded twice, setting\nserialized_rollback=True disables the\npost_migrate signal when flushing the test\ndatabase.
Regardless of the value of the DEBUG setting in your configuration\nfile, all Django tests run with DEBUG=False. This is to ensure that\nthe observed output of your code matches what will be seen in a production\nsetting.
Caches are not cleared after each test, and running manage.py test fooapp\ncan insert data from the tests into the cache of a live system if you run your\ntests in production because, unlike databases, a separate "test cache" is not\nused. This behavior may change in the future.
When you run your tests, you'll see a number of messages as the test runner\nprepares itself. You can control the level of detail of these messages with the\nverbosity option on the command line:
Creating test database...\nCreating table myapp_animal\nCreating table myapp_mineral\nThis tells you that the test runner is creating a test database, as described\nin the previous section.
\nOnce the test database has been created, Django will run your tests.\nIf everything goes well, you'll see something like this:
\n----------------------------------------------------------------------\nRan 22 tests in 0.221s\n\nOK\nIf there are test failures, however, you'll see full details about which tests\nfailed:
\n======================================================================\nFAIL: test_was_published_recently_with_future_poll (polls.tests.PollMethodTests)\n----------------------------------------------------------------------\nTraceback (most recent call last):\n File "/dev/mysite/polls/tests.py", line 16, in test_was_published_recently_with_future_poll\n self.assertIs(future_poll.was_published_recently(), False)\nAssertionError: True is not False\n\n----------------------------------------------------------------------\nRan 1 test in 0.003s\n\nFAILED (failures=1)\nA full explanation of this error output is beyond the scope of this document,\nbut it's pretty intuitive. You can consult the documentation of Python's\nunittest library for details.
Note that the return code for the test-runner script is 1 for any number of\nfailed tests (whether the failure was caused by an error, a failed assertion,\nor an unexpected success). If all the tests pass, the return code is 0. This\nfeature is useful if you're using the test-runner script in a shell script and\nneed to test for success or failure at that level.
\nAs long as your tests are properly isolated, you can run them in parallel to\ngain a speed up on multi-core hardware. See test --parallel.
The default password hasher is rather slow by design. If you're authenticating\nmany users in your tests, you may want to use a custom settings file and set\nthe PASSWORD_HASHERS setting to a faster hashing algorithm:
PASSWORD_HASHERS = [\n "django.contrib.auth.hashers.MD5PasswordHasher",\n]\nDon't forget to also include in PASSWORD_HASHERS any hashing\nalgorithm used in fixtures, if any.
The test --keepdb option preserves the test database between test\nruns. It skips the create and destroy actions which can greatly decrease the\ntime to run tests.
The InMemoryStorage is a convenient way to\nprevent disk access for media files. All data is kept in memory, then it gets\ndiscarded after tests run.