Тестування 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`** -- повертає клас моделі User, налаштований у `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-email, надіслані під час тесту. Вона автоматично перемикає email-бекенд на in-memory бекенд `locmem` -- не потрібно вручну перевизначати `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. Вона працює з будь-яким маркером і будь-яким scope, що має сенс для вашої організації коду -- `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`, оскільки кожен тест все одно відкочує власні зміни всередині транзакції бази даних. Постійна база даних зберігає лише схему та будь-які початкові дані, завантажені на початку сеансу -- тести не можуть постійно записувати рядки в неї.
**Виняток:** тести з позначкою `transaction=True` фіксують дані в базі даних. У поєднанні з `--reuse-db` зафіксовані рядки з одного сеансу переживають у наступний. Або уникайте поєднання `transaction=True` з `--reuse-db`, або додайте session-scoped teardown-фікстуру, що видаляє зафіксовані рядки.
## `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` (яка запускає застосунок у тому самому процесі) є простішою і швидшою.