Testing Django Apps with pytest-django
#pytest-django bridges the pytest ecosystem with Django's test infrastructure. It gives you all pytest features — fixtures, parametrize, marks, plugins — while still managing Django's database, test client, and settings.
## Installation and setup
```bash
pip install pytest-django
```
Tell pytest where your Django settings live by adding to `pytest.ini` in the project root:
```ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
```
Without this line pytest-django cannot bootstrap Django, and any import from your models will raise `django.core.exceptions.AppRegistryNotReady`.
## Database access is disabled by default
The most important rule in pytest-django: **database access is off by default.** Any test that tries to query the database will raise an error unless you explicitly grant access. This is intentional — tests that don't need the database should never pay the cost or risk the side effects of one that does.
Enable access per test with the `@pytest.mark.django_db` marker:
```python
import pytest
from myapp.models import Task
@pytest.mark.django_db
def test_task_creation():
task = Task.objects.create(title='Buy milk')
assert Task.objects.count() == 1
assert task.title == 'Buy milk'
```
## Transaction isolation
Each `@pytest.mark.django_db` test runs inside a database transaction that is **rolled back** after the test completes. Every test starts with a clean state and cannot pollute other tests through leftover rows:
```python
@pytest.mark.django_db
def test_a():
Task.objects.create(title='Task from test_a')
assert Task.objects.count() == 1
@pytest.mark.django_db
def test_b():
assert Task.objects.count() == 0 # test_a's row was rolled back
```
For tests that need **real** committed transactions — code using `on_commit()` hooks, `select_for_update()`, or cross-process database reads — use `@pytest.mark.django_db(transaction=True)`. This mode flushes the database after each test instead of rolling back, which is slower but accurate for transaction-sensitive code.
## Key built-in fixtures
pytest-django provides several fixtures automatically, injected by parameter name:
**`client`** — a Django `TestClient` that sends HTTP requests through the full Django stack (routing, middleware, views) without starting a real server:
```python
@pytest.mark.django_db
def test_task_list(client):
response = client.get('/tasks/')
assert response.status_code == 200
```
**`rf`** — a `RequestFactory` that builds `HttpRequest` objects directly, bypassing URL routing and all middleware. Use it to test a view function in complete isolation:
```python
from myapp.views import task_list
@pytest.mark.django_db
def test_task_list_view(rf):
request = rf.get('/tasks/')
response = task_list(request)
assert response.status_code == 200
```
**`admin_client`** — like `client` but pre-authenticated as a Django superuser. Useful for testing admin views without creating credentials manually.
**`settings`** — lets you override any Django setting for the duration of one test. Changes revert automatically after the test finishes:
```python
def test_custom_cache(settings):
settings.CACHES = {
'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}
}
from django.core.cache import cache
cache.set('key', 'value', 30)
assert cache.get('key') == 'value'
```
**`django_user_model`** — returns the User model class configured in `AUTH_USER_MODEL`. Always prefer this over importing `User` directly so your tests work with custom user models:
```python
@pytest.mark.django_db
def test_user_creation(django_user_model):
user = django_user_model.objects.create_user(username='alice', password='x')
assert user.username == 'alice'
```
## Granting DB access to fixtures
When a fixture needs to query the database, add the built-in `db` fixture as a parameter. This is the fixture-level equivalent of `@pytest.mark.django_db`:
```python
@pytest.fixture
def sample_task(db):
from myapp.models import Task
return Task.objects.create(title='Fixture task')
@pytest.mark.django_db
def test_task_is_incomplete(sample_task):
assert sample_task.completed is False
```
If the test itself carries `@pytest.mark.django_db`, its fixtures inherit database access automatically — you do not need to add `db` to every fixture. The `db` parameter is mainly needed when the fixture lives in `conftest.py` and is used across multiple test files where some tests may not carry the marker.
## Email testing with `mailoutbox`
The `mailoutbox` fixture intercepts all outgoing Django emails sent during a test. It automatically switches the email backend to Django's in-memory `locmem` backend — no manual `settings.EMAIL_BACKEND` override needed:
```python
import pytest
@pytest.mark.django_db
def test_welcome_email_is_sent(mailoutbox, django_user_model):
django_user_model.objects.create_user(username='alice', password='x')
assert len(mailoutbox) == 1
msg = mailoutbox[0]
assert msg.subject == 'Welcome, alice!'
assert '[email protected]' in msg.to
```
`mailoutbox` is a list of `django.core.mail.EmailMessage` objects. Each message exposes `subject`, `body`, `from_email`, `to`, `cc`, `bcc`, and `attachments`. The list resets to empty before each test automatically — no manual `mail.outbox.clear()` needed.
The alternative is to set `settings.EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'` in the test and read `django.core.mail.outbox` directly. Both work, but `mailoutbox` is idiomatic pytest-django: no imports, no cleanup, and guaranteed isolation between tests.
## Class-level marker with `pytestmark`
Repeating `@pytest.mark.django_db` on every method in a test class is noisy. Use `pytestmark` to apply the marker to an entire class or module:
```python
import pytest
from myapp.models import Task
class TestTaskModel:
pytestmark = pytest.mark.django_db # applies to every method in this class
def test_creation(self):
task = Task.objects.create(title='Buy milk')
assert Task.objects.count() == 1
def test_default_completed(self):
task = Task.objects.create(title='New task')
assert task.completed is False
```
At module level, `pytestmark` marks every test function in the file:
```python
# tests/test_models.py
import pytest
pytestmark = pytest.mark.django_db # every function in this module gets DB access
```
`pytestmark` is a standard pytest convention, not specific to pytest-django. It works with any marker and any scope that makes sense for your organisation — a module-level `pytestmark` is common for dedicated model test files.
## Test database lifecycle and `--reuse-db`
By default, pytest-django creates a fresh test database at the start of every `pytest` run and destroys it when the run finishes. For projects with many migrations this adds significant startup time on each run.
The `--reuse-db` flag keeps the test database between runs. On subsequent runs, pytest-django checks for unapplied migrations and applies only new ones:
```bash
pytest --reuse-db # first run: creates DB; subsequent runs: reuse it
pytest --create-db # force a clean rebuild regardless of current state
```
Typical setup for large projects:
```ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
addopts = --reuse-db
```
Then when you know the schema changed fundamentally (migrations squashed, renamed):
```bash
pytest --create-db
```
`--reuse-db` is safe with the default `transaction=False` mode because each test still rolls back its own changes inside a database transaction. The persistent database only holds the schema and any seed data loaded at session start — tests cannot permanently write rows into it.
**Exception:** tests marked `transaction=True` commit data to the database. Combined with `--reuse-db`, committed rows from one session survive into the next. Either avoid mixing `transaction=True` with `--reuse-db`, or add a session-scoped teardown fixture that deletes the committed rows.
## `live_server` — tests with a real HTTP server
The `live_server` fixture starts a real WSGI server on a random port and yields an object whose `.url` attribute is the server's base URL:
```python
@pytest.mark.django_db(transaction=True)
def test_homepage_over_http(live_server):
import urllib.request
resp = urllib.request.urlopen(f'{live_server.url}/')
assert resp.status == 200
```
`live_server` always requires `transaction=True`. The server runs in a separate thread — without actual committed rows, the server thread cannot see data created in the test thread's rolled-back transaction.
Use `live_server` for browser-automation tests (Selenium, Playwright) or when you must verify that the full WSGI stack (server, middleware, views) works end to end over a real TCP connection. For all other view and API tests, the `client` fixture (which runs the app in-process) is simpler and faster.