pytest-django

4.12.0 · active · verified Wed Apr 08

pytest-django is an active plugin for the pytest testing framework that enables efficient testing of Django projects and applications. It integrates pytest's powerful fixture system, reduced boilerplate, and advanced test capabilities with Django's ORM and components. The library maintains a regular release cadence, with multiple minor versions and occasional major updates throughout the year, ensuring compatibility with the latest Django and Python versions.

Warnings

breaking Major versions of pytest-django often drop support for older, unsupported Python, Django, and pytest versions. Ensure your environment meets the minimum requirements for the pytest-django version you are installing.
Fix: Always check the `pytest-django` changelog or documentation for specific compatibility requirements before upgrading. Upgrade Python, Django, or pytest as needed.
gotcha By default, Django's `DEBUG` setting is set to `False` during test runs, regardless of its value in your settings file. This aligns with Django's default test runner behavior to simulate a production environment.
Fix: If you need `DEBUG` to be `True` for specific tests, use the `settings` fixture to explicitly override it: `def test_my_feature(settings): settings.DEBUG = True`.
gotcha Tests that attempt to access the database without explicit permission will fail. `pytest-django` requires you to explicitly mark tests or request fixtures that need database access.
Fix: Use the `@pytest.mark.django_db` decorator on your test functions, or request the `db`, `transactional_db`, or `django_db_reset_sequences` fixtures.
gotcha Incorrectly configuring `DJANGO_SETTINGS_MODULE` can lead to import errors (`"could not import myproject.settings"`) or tests running without the proper Django environment.
Fix: Specify `DJANGO_SETTINGS_MODULE` in your `pytest.ini` (e.g., `[pytest] DJANGO_SETTINGS_MODULE = yourproject.settings`), `pyproject.toml`, as an environment variable, or via the `--ds` command-line flag.
gotcha Using the `--reuse-db` option significantly speeds up test runs by keeping the database between sessions. However, it will not automatically pick up schema changes. If models are altered, the database schema will be out of sync.
Fix: After making schema changes, run `pytest --create-db` (or `pytest --reuse-db --create-db`) once to force the test database to be re-created with the new schema. Subsequent runs can then use `--reuse-db` again.
gotcha Directly importing your Django project's `settings.py` module (e.g., `from myproject import settings`) in test files can cause issues with `pytest-django`'s setting overrides or when settings are dynamically configured.
Fix: Always import `settings` from `django.conf` (e.g., `from django.conf import settings`) for general access, and use the `settings` pytest fixture to override individual settings within tests.

Install

pip install pytest-django Install latest version

Imports

pytest.mark.django_db
```
import pytest

@pytest.mark.django_db
def test_my_database_function():
    ...
```
Use this marker on test functions that require database access. This ensures Django's database setup and transaction management are applied.
settings (fixture)
```
def test_with_custom_setting(settings):
    settings.DEBUG = True
    assert settings.DEBUG is True
```
Always use the `settings` fixture to override Django settings within tests. Directly importing your project's `settings.py` module in tests will bypass `pytest-django`'s mechanisms and Django's `override_settings` which can lead to stale or incorrect setting values.

client (fixture)

def test_my_view(client):
    response = client.get('/my-url/')
    assert response.status_code == 200

Provides an instance of `django.test.Client` for making requests in tests.

admin_client (fixture)

def test_admin_view(admin_client):
    response = admin_client.get('/admin/')
    assert response.status_code == 200

Provides an instance of `django.test.Client` logged in as a superuser.

Quickstart

1. Create a `pytest.ini` file in your project root, specifying `DJANGO_SETTINGS_MODULE` to point to your Django settings file. This is crucial for pytest-django to set up the Django environment. 2. Define your Django models as usual. 3. Write test functions, using the `@pytest.mark.django_db` decorator or by requesting the `db` fixture for any test that interacts with the database. This enables transaction management and ensures tests are isolated. 4. Run tests with `pytest` in your project root.

# myproject/pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
addopts = --reuse-db

# myproject/myproject/settings.py (abbreviated)
# ... standard Django settings ...
INSTALLED_APPS = [
    # ...
    'myapp',
    # ...
]

# myproject/myapp/models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)

    def __str__(self):
        return self.title

# myproject/myapp/tests.py
import pytest
from myapp.models import Book

@pytest.mark.django_db
def test_book_creation():
    # The 'db' fixture or 'pytest.mark.django_db' is required for database access.
    book = Book.objects.create(title='The Great Adventure', author='Jane Doe')
    assert Book.objects.count() == 1
    assert book.title == 'The Great Adventure'

view raw JSON →