Тестирование Django-приложений с pytest-django
#pytest-django соединяет экосистему pytest с тестовой инфраструктурой Django. Он даёт вам все возможности pytest -- фикстуры, parametrize, марки, плагины -- при этом управляя базой данных Django, тестовым клиентом и настройками.
## Установка и настройка
```bash
pip install pytest-django
```
Укажите pytest расположение настроек Django, добавив в `pytest.ini` в корне проекта:
```ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
```
Без этой строки pytest-django не сможет инициализировать Django, и любой импорт из ваших моделей вызовет `django.core.exceptions.AppRegistryNotReady`.
## Доступ к базе данных отключён по умолчанию
Важнейшее правило pytest-django: **доступ к базе данных отключён по умолчанию.** Любой тест, пытающийся обратиться к базе данных, вызовет ошибку, если только вы явно не разрешили доступ. Это сделано намеренно -- тесты, которым не нужна база данных, никогда не должны платить её цену или рисковать побочными эффектами.
Включите доступ для конкретного теста с помощью маркера `@pytest.mark.django_db`:
```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'
```
## Изоляция транзакций
Каждый тест с `@pytest.mark.django_db` выполняется внутри транзакции базы данных, которая **откатывается** после завершения теста. Каждый тест начинается с чистым состоянием и не может загрязнить другие тесты оставшимися строками:
```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 была откатана
```
Для тестов, которым нужны **реально** зафиксированные транзакции -- код с хуками `on_commit()`, `select_for_update()` или чтением базы данных из другого процесса -- используйте `@pytest.mark.django_db(transaction=True)`. Этот режим сбрасывает базу данных после каждого теста вместо отката, что медленнее, но точнее для кода, чувствительного к транзакциям.
## Ключевые встроенные фикстуры
pytest-django предоставляет несколько фикстур автоматически, внедряемых по имени параметра:
**`client`** -- Django `TestClient`, отправляющий HTTP-запросы через весь стек Django (маршрутизация, промежуточное ПО, представления) без запуска реального сервера:
```python
@pytest.mark.django_db
def test_task_list(client):
response = client.get('/tasks/')
assert response.status_code == 200
```
**`rf`** -- `RequestFactory`, строящий объекты `HttpRequest` напрямую, минуя URL-маршрутизацию и всё промежуточное ПО. Используйте его для тестирования функции представления в полной изоляции:
```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`** -- как `client`, но предварительно аутентифицированный как суперпользователь Django. Полезен для тестирования административных представлений без ручного создания учётных данных.
**`settings`** -- позволяет переопределить любую настройку Django на время одного теста. Изменения автоматически возвращаются после завершения теста:
```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`** -- возвращает класс модели пользователя, настроенный в `AUTH_USER_MODEL`. Всегда предпочитайте его прямому импорту `User`, чтобы ваши тесты работали с кастомными моделями пользователей:
```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'
```
## Предоставление доступа к БД фикстурам
Когда фикстуре нужно обратиться к базе данных, добавьте встроенную фикстуру `db` как параметр. Это эквивалент `@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
```
Если сам тест несёт `@pytest.mark.django_db`, его фикстуры автоматически наследуют доступ к базе данных -- не нужно добавлять `db` в каждую фикстуру. Параметр `db` нужен главным образом когда фикстура находится в `conftest.py` и используется в нескольких тестовых файлах, где некоторые тесты могут не нести маркер.
## Тестирование email с `mailoutbox`
Фикстура `mailoutbox` перехватывает все исходящие письма Django, отправленные во время теста. Она автоматически переключает бэкенд электронной почты на in-memory бэкенд `locmem` Django -- ручное переопределение `settings.EMAIL_BACKEND` не нужно:
```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` -- список объектов `django.core.mail.EmailMessage`. Каждое сообщение предоставляет `subject`, `body`, `from_email`, `to`, `cc`, `bcc` и `attachments`. Список автоматически очищается перед каждым тестом -- ручной `mail.outbox.clear()` не нужен.
Альтернатива -- установить `settings.EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend'` в тесте и читать `django.core.mail.outbox` напрямую. Оба способа работают, но `mailoutbox` -- идиоматический pytest-django: никаких импортов, никакой очистки и гарантированная изоляция между тестами.
## Маркер на уровне класса с `pytestmark`
Повторять `@pytest.mark.django_db` на каждом методе тестового класса -- избыточно. Используйте `pytestmark` для применения маркера к целому классу или модулю:
```python
import pytest
from myapp.models import Task
class TestTaskModel:
pytestmark = pytest.mark.django_db # применяется к каждому методу в этом классе
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
```
На уровне модуля `pytestmark` помечает каждую тестовую функцию в файле:
```python
# tests/test_models.py
import pytest
pytestmark = pytest.mark.django_db # каждая функция в этом модуле получает доступ к БД
```
`pytestmark` -- стандартное соглашение pytest, а не специфика pytest-django. Работает с любым маркером и любым уровнем, подходящим для вашей организации кода -- `pytestmark` на уровне модуля часто используется в выделенных файлах тестов моделей.
## Жизненный цикл тестовой БД и `--reuse-db`
По умолчанию pytest-django создаёт свежую тестовую базу данных в начале каждого запуска `pytest` и уничтожает её по завершении. Для проектов с большим количеством миграций это добавляет значительное время старта при каждом запуске.
Флаг `--reuse-db` сохраняет тестовую базу данных между запусками. При последующих запусках pytest-django проверяет наличие непримерённых миграций и применяет только новые:
```bash
pytest --reuse-db # первый запуск: создаёт БД; последующие: переиспользуют
pytest --create-db # принудительное пересоздание независимо от текущего состояния
```
Типичная настройка для крупных проектов:
```ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
addopts = --reuse-db
```
Когда вы знаете, что схема изменилась фундаментально (миграции объединены, переименованы):
```bash
pytest --create-db
```
`--reuse-db` безопасен с дефолтным режимом `transaction=False`, поскольку каждый тест по-прежнему откатывает свои изменения внутри транзакции базы данных. Постоянная база данных хранит только схему и seed-данные, загруженные в начале сессии -- тесты не могут постоянно записывать строки в неё.
**Исключение:** тесты, помеченные `transaction=True`, фиксируют данные в базе данных. В сочетании с `--reuse-db` зафиксированные строки из одной сессии переживают следующую. Либо избегайте сочетания `transaction=True` с `--reuse-db`, либо добавьте фикстуру завершения уровня session, удаляющую зафиксированные строки.
## `live_server` -- тесты с реальным HTTP-сервером
Фикстура `live_server` запускает реальный WSGI-сервер на случайном порту и возвращает объект, атрибут `.url` которого является базовым 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` всегда требует `transaction=True`. Сервер работает в отдельном потоке -- без реально зафиксированных строк поток сервера не видит данные, созданные в откатанной транзакции потока теста.
Используйте `live_server` для тестов с автоматизацией браузера (Selenium, Playwright) или когда нужно проверить что полный стек WSGI (сервер, промежуточное ПО, представления) работает от начала до конца через реальное TCP-соединение. Для всех прочих тестов представлений и API фикстура `client` (запускающая приложение в процессе) проще и быстрее.