Welcome to pytest-django’s documentation!

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

• Getting started with pytest and pytest-django
  • Introduction
  • Talks, articles and blog posts
  • Step 1: Installation
  • Step 2: Point pytest to your Django settings
  • Step 3: Run your test suite
  • Next steps
  • Stuck? Need help?
• Configuring Django settings
  • The environment variable DJANGO_SETTINGS_MODULE
  • Command line option --ds=SETTINGS
  • pytest.ini settings
  • Order of choosing settings
  • Using django-configurations
  • Using django.conf.settings.configure()
• Managing the Python path
  • Automatic looking for of Django projects
  • Managing the Python path explicitly
    • Managing your project with virtualenv, pip and editable mode
    • Using pytest-pythonpath
• Usage and invocations
  • Basic usage
  • Additional command line options
    • --fail-on-template-vars - fail for invalid variables in templates
  • Running tests in parallel with pytest-xdist
• Database creation/re-use
  • Enabling database access in tests
  • Testing transactions
  • Tests requiring multiple databases
  • --reuse-db - reuse the testing database between test runs
  • --create-db - force re creation of the test database
  • Example work flow with --reuse-db and --create-db.
  • --nomigrations - Disable Django 1.7+ migrations
  • Advanced database configuration
    • Fixtures
    • Examples
• Django helpers
  • Markers
    • pytest.mark.django_db(transaction=False) - request database access
    • pytest.mark.urls - override the urlconf
    • pytest.mark.ignore_template_errors - ignore invalid template variables
  • Fixtures
    • rf - RequestFactory
    • client - django.test.Client
    • admin_client - django.test.Client logged in as admin
    • admin_user - a admin user (superuser)
    • django_user_model
    • django_username_field
    • db
    • transactional_db
    • live_server
    • settings
• FAQ
  • I see an error saying “could not import myproject.settings”
  • How can I make sure that all my tests run with a specific locale?
  • My tests are not being found. Why not?
  • Does pytest-django work with the pytest-xdist plugin?
  • How can I use manage.py test with pytest-django?
  • How/where can I get help with pytest/pytest-django?
• Contributing to pytest-django
  • Community
  • In a nutshell
  • Contributing Code
    • Getting the source code
    • Syntax and conventions
    • Process
    • Tests
  • Contributing Documentation
• Changelog
  • 3.0.0
    • Bug fixes
    • Features
    • Compatibility
  • 2.9.1
    • Bug fixes
  • 2.9.0
    • Features
    • Bug fixes
    • Compatibility
  • 2.8.0
    • Features
    • Bug fixes
  • 2.7.0
    • Features
    • Bugfixes
  • 2.6.2
  • 2.6.1
  • 2.6.0
  • 2.5.1
  • 2.5.0
  • 2.4.0
  • 2.3.1
  • 2.3.0
  • 2.2.1
  • 2.2.0
  • 2.1.0
  • 2.0.1
  • 2.0.0
  • 1.4
  • 1.3
  • 1.2.2
  • 1.2.1
  • 1.2
  • 1.1.1
  • 1.1

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
• Database re-use: no need to re-create the test database for every test run.
• 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.

Quick Start

1. pip install pytest-django
2. Make sure DJANGO_SETTINGS_MODULE is defined and and run tests with the pytest command.
3. (Optionally) If you put your tests under a tests directory (the standard Django application layout), and your files are not named test_FOO.py, see the FAQ My tests are not being found. Why not?.

Bugs? Feature suggestions?

Report issues and feature requests at the github issue tracker.

Indices and tables

• Index
• Module Index