Unit tests¶

Django comes with a test suite of its own, in the tests directory of the code base. It’s our policy to make sure all tests pass at all times.

We appreciate any and all contributions to the test suite!

The Django tests all use the testing infrastructure that ships with Django for testing applications. See Writing and running tests for an explanation of how to write new tests.

Contrib apps¶

Tests for contrib apps can be found in the tests/ directory, typically under <app_name>_tests. For example, tests for contrib.auth are located in tests/auth_tests.

Tips for writing tests¶

Isolating model registration¶

To avoid polluting the global apps registry and prevent unnecessary table creation, models defined in a test method should be bound to a temporary Apps instance:

from django.apps.registry import Apps
from django.db import models
from django.test import SimpleTestCase

class TestModelDefinition(SimpleTestCase):
    def test_model_definition(self):
        test_apps = Apps(['app_label'])

        class TestModel(models.Model):
            class Meta:
                apps = test_apps
        ...

django.test.utils.isolate_apps(*app_labels, attr_name=None, kwarg_name=None)¶

Since this pattern involves a lot of boilerplate, Django provides the isolate_apps() decorator. It’s used like this:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

class TestModelDefinition(SimpleTestCase):
    @isolate_apps('app_label')
    def test_model_definition(self):
        class TestModel(models.Model):
            pass
        ...

Setting app_label

Models defined in a test method with no explicit app_label are automatically assigned the label of the app in which their test class is located.

In order to make sure the models defined within the context of isolate_apps() instances are correctly installed, you should pass the set of targeted app_label as arguments:

tests/app_label/tests.py¶

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

class TestModelDefinition(SimpleTestCase):
    @isolate_apps('app_label', 'other_app_label')
    def test_model_definition(self):
        # This model automatically receives app_label='app_label'
        class TestModel(models.Model):
            pass

        class OtherAppModel(models.Model):
            class Meta:
                app_label = 'other_app_label'
        ...

The decorator can also be applied to classes:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

@isolate_apps('app_label')
class TestModelDefinition(SimpleTestCase):
    def test_model_definition(self):
        class TestModel(models.Model):
            pass
        ...

The temporary Apps instance used to isolate model registration can be retrieved as an attribute when used as a class decorator by using the attr_name parameter:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

@isolate_apps('app_label', attr_name='apps')
class TestModelDefinition(SimpleTestCase):
    def test_model_definition(self):
        class TestModel(models.Model):
            pass
        self.assertIs(self.apps.get_model('app_label', 'TestModel'), TestModel)

Or as an argument on the test method when used as a method decorator by using the kwarg_name parameter:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

class TestModelDefinition(SimpleTestCase):
    @isolate_apps('app_label', kwarg_name='apps')
    def test_model_definition(self, apps):
        class TestModel(models.Model):
            pass
        self.assertIs(apps.get_model('app_label', 'TestModel'), TestModel)

Django 3.2.19 documentation

Unit tests¶

Running the unit tests¶

Quickstart¶

Running tests using `tox`¶

Testing other Python versions and database backends¶

Running the JavaScript tests¶

Running tests using `django-docker-box`¶

Using another `settings` module¶

Running only some of the tests¶

Running the Selenium tests¶

Running all the tests¶

Code coverage¶

Contrib apps¶

Troubleshooting¶

Test suite hangs or shows failures on `main` branch¶

Many test failures with `UnicodeEncodeError`¶

Tests that only fail in combination¶

Seeing the SQL queries run during a test¶

Seeing the full traceback of a test failure¶

Tips for writing tests¶

Isolating model registration¶

Table of Contents

Previous topic

Next topic

Last update:

Django 3.2.19 documentation

Unit tests¶

Running the unit tests¶

Quickstart¶

Running tests using tox¶

Testing other Python versions and database backends¶

Running the JavaScript tests¶

Running tests using django-docker-box¶

Using another settings module¶

Running only some of the tests¶

Running the Selenium tests¶

Running all the tests¶

Code coverage¶

Contrib apps¶

Troubleshooting¶

Test suite hangs or shows failures on main branch¶

Many test failures with UnicodeEncodeError¶

Tests that only fail in combination¶

Seeing the SQL queries run during a test¶

Seeing the full traceback of a test failure¶

Tips for writing tests¶

Isolating model registration¶

Last update:

Running tests using `tox`¶

Running tests using `django-docker-box`¶

Using another `settings` module¶

Test suite hangs or shows failures on `main` branch¶

Many test failures with `UnicodeEncodeError`¶