Project Example

This is a full example on how to start a Django project with a BDD test setup that runs from commit #1. (See Getting Started if you want to start using Behave with an existing Django project.)

We will use modern Python tooling. No need to worry about managing virtual environments and project dependencies. uv will take care of everything.

Django with BDD from Scratch

Bootstrap your Python project.

mkdir myproject
cd myproject
uv init
rm main.py  # we don't need uv's example module

Turn it into a Django project.

uv add django
uv run django-admin startproject application .

Add Behave to your development dependencies.

uv add --dev behave-django

Integrate Behave with your Django project by adding something like this to application/settings.py:

try:
    import behave_django
except ImportError:
    print("Behave not available. Probably running in production.")
else:
    INSTALLED_APPS += ["behave_django"]

Add the following to pyproject.toml to tell Behave where to look for the tests:

[tool.behave]
paths = ["tests"]

Create a tests folder and add your first feature file to start behavior-driven development (BDD), e.g.

mkdir -p tests/features
touch tests/features/admin-login.feature

Add a test scenario to the empty feature file, e.g.

Feature: Verify Django Admin is available

Scenario: Use the Django Admin login form
    Given we have created a Django superuser
    And we have navigated to the Django Admin login page
    When we enter username and password
    Then the Django Admin overview is shown

Create a steps folder and run Behave using the Django management command behave to show you the missing step implementations.

mkdir tests/steps
uv run manage.py behave

Note that Behave will print out Python code that you can copy and paste.

Now, create a Python module for your step implementation, say, tests/steps/admin_login.py, and paste the output into that file.

If you want to run Python code before or after features, scenarios, steps or tags add a tests/environment.py file (see the Behave docs for details).

Your setup should now look like this:

├── application
│   ├── asgi.py
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── pyproject.toml
├── README.md
├── tests
│   ├── environment.py
│   ├── features
│   │   └── admin-login.feature
│   └── steps
│       └── admin_login.py
└── uv.lock

You can now start implementing the business logic of your steps and tweak your test environment using Python code.

Copier Template

Tip

You can create a Django starter project with this layout using the Painless CI/CD Copier template for Django.