behave / pytest-bdd Setup

behave and pytest-bdd connect Gherkin feature files to Python step definitions. pytest-bdd integrates with existing pytest suites; behave is a standalone BDD runner.

Recipe

# pytest-bdd (recommended with pytest)
uv add --group dev pytest-bdd
 
# behave (standalone)
uv add --group dev behave

project/
├── features/
│   ├── invoice.feature
│   └── steps/
│       └── invoice_steps.py
└── tests/
    └── test_bdd.py

When to reach for this:

• Adding BDD to an existing pytest project (pytest-bdd)
• Greenfield BDD with dedicated runner (behave)
• Connecting feature files to FastAPI/Django test clients

Working Example

# features/invoice.feature
Feature: Invoice API
  Scenario: Create draft invoice
    Given the API is running
    When I POST /invoices with amount 100.00
    Then the response status is 201

# features/steps/invoice_steps.py (pytest-bdd)
from pytest_bdd import scenarios, given, when, then, parsers
from fastapi.testclient import TestClient
from myapp.main import app
 
scenarios("../invoice.feature")
 
client = TestClient(app)
_context = {}
 
@given("the API is running")
def api_running():
    _context["client"] = client
 
@when(parsers.parse("I POST /invoices with amount {amount:f}"))
def post_invoice(amount):
    _context["response"] = _context["client"].post(
        "/invoices", json={"amount": amount, "currency": "USD"}
    )
 
@then(parsers.parse("the response status is {status:d}"))
def check_status(status):
    assert _context["response"].status_code == status

uv run pytest features/steps/invoice_steps.py -v

What this demonstrates:

• Feature file in features/ directory
• scenarios() links feature to step module
• @given/@when/@then decorators map Gherkin to Python
• parsers.parse extracts parameters from step text

Deep Dive

pytest-bdd vs behave

behave Setup

features/
├── environment.py    # hooks: before_all, after_scenario
├── invoice.feature
└── steps/
    └── invoice_steps.py

uv run behave features/

Gotchas

• Global context dict - state leaks between scenarios. Fix: use pytest fixtures or behave context per scenario.
• scenarios() path wrong - no tests collected. Fix: path relative to the steps file.
• Step text mismatch - step not found error. Fix: Gherkin text must match decorator exactly (or use parsers).
• Running features without step files - 0 tests. Fix: ensure scenarios() import in a collected test module.
• behave and pytest-bdd mixed - two runners, duplicate steps. Fix: pick one tool per project.

Alternatives

FAQs

Related

• Gherkin Syntax - writing features
• Step Definitions - step patterns
• Gherkin to CI Pipeline - CI integration
• pytest Setup - pytest config

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.