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.

Source Distribution

django-setuptest-0.2.1.tar.gz (9.5 kB view hashes)

Uploaded source

Built Distribution

django_setuptest-0.2.1-py2.7.egg (12.5 kB view hashes)

Uploaded 2 7

Supported by

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