Skip to main content

Simple test suite enabling Django app testing via $ python test

Project description

Django Setuptest

Simple module enabling Django app testing via $ python test.

Normally when you execute $ python test for Django related modules you’re almost certain to run into DJANGO_SETTINGS_MODULE environment variable issues, e.g.:

ImportError: Settings cannot be imported, because environment variable

This module overcomes this by configuring the DJANGO_SETTINGS_MODULE environment variable before executing your test suite. As a bonus it also generates Coverage and PEP 8 reports as part of the test.


  1. Provide a test_suite argument to the setup call specifying the setuptest.setuptest.SetupTestSuite test suite, e.g.:

        # ...

    Alternatively provide a cmdclass test argument to the setup call specifying the setuptest.test command, e.g.:

    from setuptest import test
        # ...
        cmdclass={'test': test},

    This overrides Python’s builtin test command to enable the Django testrunner as well as allowing you to pass --failfast as a commandline argument, i.e.:

    $ python test --failfast

    For the cmdclass method to work django-setuptools should be installed and available in your Python path prior to running the test command, in which case django-setuptest is not required to be specified as part of the tests_required argument as detailed next.

  2. Provide a tests_require argument to the setup call including django-setuptest (required only if not already installed) and other package dependencies needed to execute the tests, e.g.:

        # ...
  3. Specify your test specific Django settings in a test_settings module in the same path as your app’s These settings will be used when executing the tests, e.g. in

    DATABASE_ENGINE = 'sqlite3'
  4. In order for the test suite to find your tests you must provide either a packages or py_modules argument to the setup call, e.g.:

    from setuptools import setup, find_packages
        # ...
    # Or alternatively...
        # ...


Once correctly configured you can execute tests from the command line:

$ python test

or, if you want the test suite to stop after the first test failure is detected:

$ python test --failfast

This should output your test results as well as Coverage and PEP 8 reports.


An XML Coverage report is generated in a file called coverage.xml and a PEP8 report is generated in a file called pep8.txt

To mute the output of the Coverage and PEP 8 reports provide the --quiet option:

$ python test --quiet

To automatically restart the test runner when code changes are detected (similar to how runserver restarts) provide the --autoreload option:

$ python test --autoreload

To only run tests for a particular test case specify the test case as the --label option:

$ python test --label app.TestCase

Or for a particular test method specify the test case’s test method as the --label option:

$ python test --label app.TestCase.test_method

Sample Output

Example output of dummy test including Coverage and PEP 8 reports:

$ python test
running test
running egg_info
writing django_dummy.egg-info/PKG-INFO
writing top-level names to django_dummy.egg-info/top_level.txt
writing dependency_links to django_dummy.egg-info/dependency_links.txt
reading manifest file 'django_dummy.egg-info/SOURCES.txt'
reading manifest template ''
writing manifest file 'django_dummy.egg-info/SOURCES.txt'
running build_ext
Creating test database for alias 'default'...
ERROR: test_something (dummy.tests.TestCase)
Traceback (most recent call last):
  File "/home/user/tmp/django-dummy/dummy/tests/", line 6, in test_something
    raise NotImplementedError('Test not implemented. Bad developer!')
NotImplementedError: Test not implemented. Bad developer!

Ran 1 test in 0.000s

FAILED (errors=1)
Destroying test database for alias 'default'...

Coverage Report:
Name              Stmts   Miss  Cover   Missing
dummy/models      20      2    90%   22, 55

PEP8 Report:
dummy/tests/ W391 blank line at end of file



Praekelt Foundation

  • Shaun Sephton
  • Hedley Roos


  • Jannis Leidel


0.2.1 (2016-01-04)

  1. Support Django 1.9.

0.2 (2015-10-30)

  1. Django 1.8 support (lamby).
  2. Exclude south_migrations from PEP8 checks (mikebryant).

0.1.6 (2015-01-13)

  1. Added saving of raw coverage data

0.1.5 (2014-09-11)

  1. Introduced support for Django 1.7.

0.1.4 (2013-06-21)

  1. South patches the test management command to handle the SOUTH_TESTS_MIGRATE setting. Apply that patch if South is installed.

0.1.3 (2013-05-23)

  1. Python 3 compatibility.

0.1.2 (2012-07-02)

  1. Exclude South migrations from Pep8.

0.1.1 (2012-06-19)

  1. Corrections to support PEP8 backwards incompatible API update.

0.0.9 (2012-06-15)

  1. Now supports running specific test classes or methods via the label option.

0.0.8 (2012-06-13)

  1. Added autoreload option restarting testrunner on code change detection.

0.0.7 (2012-06-04)

  1. Refactor into a test command allowing for failfast commandline argument.

0.0.6 (2011-09-08)

  1. Refactor, cleanup, self contained suite class.

0.0.5 (2011-09-06)

  1. Added frame hack to resolve packages and py_modules to test, no longer needs app specific test suite.

0.0.4 (2011-09-06)

  1. Refactored the app to use a callback style approach instead of monkey patching. Thanks jezdez.

0.0.3 (2011-08-30)

  1. More robust test settings import.

0.0.2 (2011-08-29)

  1. Repeat Pep 8 errors.

0.0.1 (2011-08-29)

  1. Initial release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-setuptest, version 0.2.1
Filename, size File type Python version Upload date Hashes
Filename, size django_setuptest-0.2.1-py2.7.egg (12.5 kB) File type Egg Python version 2.7 Upload date Hashes View
Filename, size django-setuptest-0.2.1.tar.gz (9.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page