Python Test Runner

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:

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:

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.pytest. Each test label can be a full Python dottedpath to a package, module, TestCase subclass, or test method. For instance:

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

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:

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-Wamanage.pytest. 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().

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:

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:

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

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:

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.

Writing unit tests in Python is fairly easy, thanks to the well-known Unittest module. What I found less obvious was how to organize those tests properly and run them all together.

Let me begin with a little bit of theory on how that module works and what it expects from your code. I will be using Python 3 for the following tutorial, but everything will work fine also with previous versions.

Cases, suites, runners, fixtures

The Unittest module borrows four basic concepts from the unit testing philosophy.

A text fixture is a function that contains the preparation of your test environment. Here you usually initialize databases, create files, prepare stuff so that your tests can work properly. Fixtures are also used to clean up the scene once finished.

Python Interpreter

A test case is a class that represents an individual unit of testing. That's the place where you make sure your code works correctly. It contains fixtures and calls to assert methods to check for and report failures.

A test suite is just a bunch of test cases together.

A test runner is a script that takes care of running the test suite.

My app needs to be tested

Now suppose that you are writing a minimalistic game made of the following objects: Player, Scenario and Thing. You are following a test-driven development so you write tests along the actual code.

Each test is contained in a module (i.e. a Python file), so you would end up with three modules/files. Let's set up a barebone test case for the Player object: with Unittest it would look something like that:

First of all import the unittest module. That was obvious. The class TestPlayer is the actual test case and follows a naming convention: Test[whatYouWantToTest]. It also extends the unittest.TestCase base object to work: a test case is always created by subclassing the parent class.

Then, each test case begins and ends with setUp() and tearDown(): those are fixtures. There you put the code that will be executed before and after each test method. They are not mandatory: you can just omit them if you don't need specific initializations or cleanups.

The 'body' of the test case is composed of test methods: test_run and test_attack in the example above. It's the place where you check that your code is running properly, with the aid of the assert methods.

Python Test Runner Download

Individual test methods' name must start with the letters test_. That's another naming convention required by the test runner to know which methods are the actual tests. More on that in a couple of seconds.

Just rinse and repeat the procedure for each class of your game and you eventually end up with several test cases, one for each component. You can then run the test cases one by one by hand, but that would be totally annoying. It's now time to set up a nice test suite and let it work for you on its own.

Organize tests in a test suite

The basic idea here is to have a new Python file runner.py alongside your tests that contains our runner. It looks something like the following:

First of all import your modules containing your tests (player, scenario and thing, remember?). Then initialize the suite and the loader by calling unittest.TestLoader() and unittest.TestSuite().

Add your tests to the test suite with suite.addTests(loader.loadTestsFromModule([your-module-here])), then initialize the test runner and fire it with runner.run(suite).

I also set the verbosity level of the test runner to 3: that's how much information you'll see in the console output.

Python Runner File

Launch the script and all your tests will be executed nicely.

Sources

Python Quiz

Python Official Documentation - Unit testing framework (link)
Python Testing - unittest introduction (link)
Wikipedia - Test fixture (link)
Voidspace - Introduction to unittest (link)