django-setuptest 0.2.1
Simple test suite enabling Django app testing via $ python setup.py test
License: BSD

Django Setuptest
================
**Simple module enabling Django app testing via $ python setup.py test.**


.. contents:: Contents
    :depth: 5

Normally when you execute ``$ python setup.py 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
    DJANGO_SETTINGS_MODULE is undefined.

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.


Installation
------------

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

    setup(
        # ...
        test_suite='setuptest.setuptest.SetupTestSuite',
    )

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

    #...

    setup(
        # ...
        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 setup.py 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.

#. 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.::

    setup(
        # ...
        tests_require=(
            'django-setuptest',
        ),
    )

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

    DATABASE_ENGINE = 'sqlite3'

    INSTALLED_APPS = (
        'myapp',
    )

#. 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
    
    setup(
        # ...
        packages=find_packages(),
    )
    
    # Or alternatively...
    
    setup(
        # ...
        py_modules=['myapp'],
    )

Usage
-----
Once correctly configured you can execute tests from the command line::
    
    $ python setup.py test
    
or, if you want the test suite to stop after the first test failure is 
detected::

    $ python setup.py test --failfast

This should output your test results as well as Coverage_ and `PEP 8`_
reports.

.. note::

    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 setup.py test --quiet

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

    $ python setup.py test --autoreload

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

    $ python setup.py test --label app.TestCase

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

    $ python setup.py test --label app.TestCase.test_method

Sample Output
-------------

Example output of dummy test including Coverage_ and `PEP 8`_ reports::

    $ python setup.py 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 'MANIFEST.in'
    writing manifest file 'django_dummy.egg-info/SOURCES.txt'
    running build_ext
    Creating test database for alias 'default'...
    E
    ======================================================================
    ERROR: test_something (dummy.tests.TestCase)
    ----------------------------------------------------------------------
    Traceback (most recent call last):
      File "/home/user/tmp/django-dummy/dummy/tests/__init__.py", 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/__init__.py:6:1: W391 blank line at end of file

    $


.. _Coverage: http://nedbatchelder.com/code/coverage/
.. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/

Authors
=======

Praekelt Foundation
-------------------
* Shaun Sephton
* Hedley Roos

Contributors
------------
* Jannis Leidel

Changelog
=========

0.2.1 (2016-01-04)
------------------
#. Support Django 1.9.

0.2 (2015-10-30)
----------------
#. Django 1.8 support (lamby).
#. Exclude south_migrations from PEP8 checks (mikebryant).

0.1.6 (2015-01-13)
------------------
#. Added saving of raw coverage data

0.1.5 (2014-09-11)
------------------
#. Introduced support for Django 1.7.

0.1.4 (2013-06-21)
------------------
#. 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)
------------------
#. Python 3 compatibility.

0.1.2 (2012-07-02)
------------------
#. Exclude South migrations from Pep8.

0.1.1 (2012-06-19)
------------------
#. Corrections to support PEP8 backwards incompatible API update.

0.0.9 (2012-06-15)
------------------
#. Now supports running specific test classes or methods via the label option.

0.0.8 (2012-06-13)
------------------
#. Added autoreload option restarting testrunner on code change detection.

0.0.7 (2012-06-04)
------------------
#. Refactor into a test command allowing for failfast commandline argument.

0.0.6 (2011-09-08)
------------------
#. Refactor, cleanup, self contained suite class.

0.0.5 (2011-09-06)
------------------
#. Added frame hack to resolve packages and py_modules to test, no longer needs app specific test suite.

0.0.4 (2011-09-06)
------------------
#. Refactored the app to use a callback style approach instead of monkey patching. Thanks `jezdez <https://github.com/jezdez>`_.

0.0.3 (2011-08-30)
------------------
#. More robust test settings import.

0.0.2 (2011-08-29)
------------------
#. Repeat Pep 8 errors.

0.0.1 (2011-08-29)
------------------
#. Initial release.