pytest-django Documentation

pytest-django is a plugin for pytest that provides a set of useful tools for testing Django applications and projects.

Quick Start

$ pip install pytest-django

Make sure DJANGO_SETTINGS_MODULE is defined (see Configuring Django settings) and make your tests discoverable (see My tests are not being found. Why?):

Example using pytest.ini or tox.ini

# -- FILE: pytest.ini (or tox.ini)
[pytest]
DJANGO_SETTINGS_MODULE = test.settings
# -- recommended but optional:
python_files = tests.py test_*.py *_tests.py

Example using pyproject.toml

# -- Example FILE: pyproject.toml
[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "test.settings"
# -- recommended but optional:
python_files = ["test_*.py", "*_test.py", "testing/python/*.py"]

Run your tests with pytest:

$ pytest

Why would I use this instead of Django’s manage.py test command?

Running the test suite with pytest offers some features that are not present in Django’s standard test mechanism:

  • Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.

  • Manage test dependencies with fixtures.

  • Run tests in multiple processes for increased speed.

  • There are a lot of other nice plugins available for pytest.

  • Easy switching: Existing unittest-style tests will still work without any modifications.

See the pytest documentation for more information on pytest.

Bugs? Feature Suggestions?

Report issues and feature requests at the GitHub issue tracker.

Table of Contents

Indices and Tables