Behave-Django

1.9.0 · active · verified Thu Apr 16

Behave-Django integrates the Behave BDD (Behavior-Driven Development) framework with Django projects, allowing developers to write human-readable feature files and step definitions to test web applications. As of its current version 1.9.0, it supports modern Python and Django versions, with a regular release cadence addressing compatibility and feature enhancements.

Common errors

```
django.db.utils.IntegrityError: (1062, "Duplicate entry '...' for key '...'')
```
cause Fixtures are not being properly reset between scenarios, leading to duplicate key errors when re-inserting data.

fix Ensure your `environment.py` includes proper `after_scenario` or `after_step` hooks for database cleanup, or upgrade to a version (1.9.0+) that fixes known fixture reset issues, especially with Django 5.2+.
```
ModuleNotFoundError: No module named 'behave_django.testcase'
```
cause Incorrect import path for the Behave-Django test case classes.

fix Change `from behave_django.testcase import ...` to `from behave_django.test_case import ...`.
```
behave-django.exceptions.ImproperlyConfigured: Django settings are not configured. Call settings.configure() or set DJANGO_SETTINGS_MODULE in your environment.
```
cause Behave-Django couldn't find your Django project settings.

fix Make sure the `DJANGO_SETTINGS_MODULE` environment variable is set to your project's settings file (e.g., `export DJANGO_SETTINGS_MODULE=myproject.settings`) before running `behave`.

Warnings

breaking The `--runner-class` option was renamed to `--runner` in behave-django 1.5.0, and it now requires `parent.module:class` syntax.
Fix: Update command-line invocations. For example, change `--runner-class my_runner` to `--runner my_module:MyRunnerClass`.
breaking Python 3.6, 3.7, Django 3.3, and 4.1 support was dropped in behave-django 1.5.0. Python 3.8 support was dropped in 1.6.0. Python 3.9 is now the minimum required. Django 5.2+ requires specific fixes in 1.6.0 and 1.9.0.
Fix: Upgrade your Python environment to 3.9+ and Django to a supported version (e.g., Django 4.2+, 5.x). Check the release notes for specific version requirements.
gotcha Automatic fixture resetting is planned for v2.0.0. In current versions, if `fixtures` are set to an empty list, they might not reset correctly, especially on Django 5.2+. This was fixed in 1.9.0 for the empty list case.
Fix: For versions prior to 1.9.0, or to be safe before 2.0.0's automatic reset, manually manage fixture cleanup in your `after_scenario` hooks if you encounter issues with fixture state persistence.
gotcha Older versions of behave-django (before 1.8.0) experienced issues with database transaction rollback due to incompatibilities with Behave 1.2.7.dev8 and later.
Fix: Upgrade to behave-django 1.8.0 or newer to ensure proper database transaction handling and rollback. This version depends on behave 1.3.3+.

Install

pip install behave-django Install stable version

Imports

DjangoBehaveTestCase

wrong:

from behave_django.testcase import DjangoBehaveTestCase

correct:

from behave_django.test_case import DjangoBehaveTestCase

The 'test_case' module uses a snake_case name, not 'testcase'.

before_all
wrong:
```
from behave_django.hooks import before_all
```
correct:
```
from behave_django.environment import before_all
```
Behave-Django hooks are typically defined directly in your project's 'environment.py' and imported via `behave_django.environment` if needed for custom setup.

Quickstart

To get started, define your `features/` directory with `.feature` files and corresponding step definitions in `features/steps/`. Behave-Django automatically detects these. An `environment.py` file is typically used for setup/teardown hooks (e.g., `before_all`, `after_scenario`). Ensure your Django settings are configured correctly for testing. You can run `behave` from your Django project root.

from django.test import TestCase

class MyFeatureTests(TestCase):
    def test_example_scenario(self):
        # Your Django-specific test logic here
        self.assertEqual(1 + 1, 2)

# features/example.feature
# Feature: Example Feature
#   Scenario: Basic addition
#     Given I have the number 1
#     And I add the number 1
#     Then the result should be 2

# features/steps/example_steps.py
# from behave import given, when, then
# from django.test import TestCase
# from behave_django.decorators import fixtures

# @fixtures(['my_fixture.json'])
# @given('I have the number {number:d}')
# def step_impl(context, number):
#     context.a = number

# @when('I add the number {number:d}')
# def step_impl(context, number):
#     context.result = context.a + number

# @then('the result should be {expected_result:d}')
# def step_impl(context, expected_result):
#     assert context.result == expected_result

view raw JSON →