django-discover-runner 1.0

Why?

Django’s own test discovery is very much tied to the directory structure of Django apps, partly due to historic reasons (the unittest library didn’t have its own discovery for a long time) and prevents Django app authors from being good Python citizens. django-discover-runner uses the official test discovery feature of the new unittest2 library which is included in Django.

By default there is no way to put project specific tests in a separate folder outside the Python package of the Django project, which is a great way to organize your code, separating the tests and non-test code. django-discover-runner helps you clean up your project tests.

There is also no way to specify fully dotted import paths to test modules, functions, class or methods to the test management command but only Django’s odd standard <appname>.<TestClassName>. django-discover-runner allows you to specify any type of label to Django’s test management command.

By default Django’s test runner will execute the tests of Django’s own contrib apps, which doesn’t make sense if you just want to run your own app’s or project’s tests. django-discover-runner fixes this by allowing you to specify which tests to run and organize your test code outside the reach of the Django test runner.

More reasons can be found in Carl Meyer’s excellent talk about Testing and Django (slides).

Installation

Install it with your favorite installer, e.g.:

pip install -U django-discover-runner

django-discover-runner requires at least Django 1.4 and also works on 1.5.x. Starting in Django 1.6 the discover runner is a built-in.

Setup

• TEST_RUNNER (required) needs to point to the DiscoverRunner class to enable it:

  TEST_RUNNER = 'discover_runner.DiscoverRunner'

• Add 'discover_runner' to your INSTALLED_APPS setting to enable the ability to override the discovery settings below when using the test management command.

• TEST_DISCOVER_TOP_LEVEL (optional) should be the directory containing your top-level package(s); in other words, the directory that should be on sys.path for your code to import. This is for example the directory containing manage.py in the new Django 1.4 project layout. The management command option is called --top-level.

• TEST_DISCOVER_PATTERN (optional) is the pattern to use when discovering tests and defaults to the unittest2 standard test*.py. The management command option is called --pattern.

Examples

django-admin.py test --settings=myapp.test_settings myapp

from os import path
TEST_DISCOVER_TOP_LEVEL = path.dirname(path.dirname(__file__))

django-admin.py test --settings=mysite.test_settings tests

import django

if django.VERSION[:2] < (1, 6):
  TEST_RUNNER = 'discover_runner.DiscoverRunner'

Changelog

Thanks

This test runner is a humble rip-off of Carl Meyer’s DiscoveryRunner which he published as a gist a while ago. All praise should be directed at him. Thanks, Carl!

This was also very much related to ticket #17365 which eventually led to the replacement of the default test runner in Django. Thanks again, Carl!