Welcome to pytest-django’s documentation!

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

• Getting started
  • Installation
  • Usage
• Configuring Django settings
  • The environment variable DJANGO_SETTINGS_MODULE
  • Command line option --ds=SETTINGS
  • pytest.ini settings
  • Using django-configurations
  • Using django.conf.settings.configure()
• Database creation/re-use
  • Enabling database access
  • 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.
• Django helpers
  • Markers
    • pytest.mark.django_db - request database access
    • pytest.mark.urls - override the urlconf
  • Fixtures
    • rf - RequestFactory
    • client - django.test.Client
    • admin_client - django.test.Client logged in as admin
    • db
    • transactional_db
    • live_server
• FAQ
  • How can I make sure that all my tests run with a specific locale?
  • My tests are not being picked up when I run py.test from the root directory. Why not?
  • How can I avoid having to type DJANGO_SETTINGS_MODULE=... to run the tests?
  • How does South and pytest-django play together?
  • Does this work with the pytest-xdist plugin?
• Contributing to pytest-django
  • Community
  • In a nutshell
  • Contributing Code
    • Getting the source code
    • Syntax and conventions
    • Process
    • Tests
  • Contributing Documentation
• Changelog
  • 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 py.test offers some features that are not present in Djangos standard test mechanism:

• Smarter test discovery (no need for from .foo import * in your test modules).
• Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.
• Injection of test depencies with funcargs
• No need to run all tests, it is easy to specify which tests to run.
• No hacks required to only run your apps, and not the 3rd party/contrib apps that is listed in your INSTALLED_APPS.
• There are a lot of other nice plugins available for py.test.
• No pain of switching: Existing unittest-style tests will still work without any modifications.

See the py.test documentation for more information on py.test.

Quick Start

1. pip install pytest-django
2. Make sure DJANGO_SETTINGS_MODULE is defined and and run tests with the py.test 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 picked up when I run py.test from the root directory. Why not?.

Requirements

The current supported versions of Python, Django and pytest are:

• Python 2.5-2.7
• Django 1.3-1.5
• py.test 2.3.4+

Bugs? Feature suggestions?

Report issues and feature requests at the github issue tracker.

Indices and tables

• Index
• Module Index