Skip to content
A Django TestRunner for the Behave BDD module
Python Cucumber
Find file
Latest commit 81d7e60 @rwillmer rwillmer Merge pull request #64 from nikolas/django19-python35
Enable automated testing on django 1.9 / python 3.5

Build Status
Tested on:

  • Python 2.7
  • Python 3.3, 3.4
  • Django v1.4-1.8

Behave still has many 3.x bugs. Please ensure the bug is with django-behave and not with Behave.


A Django TestRunner for the Behave BDD module


  • To provide a Cucumber-compatible BDD toolset for Django;
  • To work well with existing Django testing behaviour e.g. use a test database
  • To use Cucumber/Gherkin syntax.
  • To provide a library of django-useful steps.


  • add django_behave to INSTALLED_APPS
  • set TEST_RUNNER to django_behave.runner.DjangoBehaveTestSuiteRunner or django_behave.runner.DjangoBehaveOnlyTestSuiteRunner
  • add features directories to apps
  • decide which automation library you want to use
  • setup your to use this library to open browser (see below)
  • copy django_behave/features/steps/, if wanted.


Assuming you have an app called proj.apps.myapp:

Edit INSTALLED_APPS, as above. Edit TEST_RUNNER, as above.

Create proj/apps/myapp/features and proj/apps/myapp/features/steps.

Copy example_app/features/tutorial.feature to the features dir. Copy example_app/features/steps/ to the features/steps dir.

$ python test myapp

should then show you django-behave in action, finding the tutorial feature and running the tests.


The main one is the 'behave' module, of course, which provides the BDD toolset for Python.

Also used are:

  • django >= 1.4 (needed for LiveServerTestCase)
  • selenium

See requirements.txt for details.


django_behave is agnostic about which automation library you use inside the tests.

I (Rachel, original author of django-behave) like splinter (

You will need to setup a browser for use with this library.

For example, my features/ file has this:

from splinter.browser import Browser

def before_all(context):
    context.browser = Browser()

def after_all(context):
    context.browser = None


It is possible to use Behave command line options. In order to avoid conflict with Django's test options, all options meant for django-behave start with '--behave_'. For example, given the following Behave command:

behave --no-color --tags @mytag ...

this would become:

./ test --behave_no-color --behave_tags @mytag ...

In addition, the option '--behave_browser' can allow the user to specify which browser to use for testing. For example:

./ test --behave_browser firefox ...

The splinter before_all() example above could then use this option:

def before_all(context):
    context.browser = Browser(context.config.browser)


You can run all unittest2 tests with the following:


The tests use the example_proj project which has installed the example_app application.

If you're using a virtualenv, activate it before running this command, otherwise it will fail.

Something went wrong with that request. Please try again.