behave-testing

Overview

Per behave-docs:

"behave is behaviour-driven development, Python style." It employs "tests written in a natural language style, backed up by Python code."

Per behave-docs: "Behavior-driven development encourages collaboration between developers, QA and non-technical or business participants in a software project."

Per cucumber-install, Behave is in the semi-official Cucumber tier (uses Cucumber components but maintained outside the main org).

When to use

• The codebase is Python and the team uses BDD.
• Acceptance criteria are authored in Gherkin (per gherkin-from-stories).
• pytest with parametrize isn't sufficient - non-engineers read the tests.

Step 1 - Install

pip install behave

Step 2 - Project layout

Behave's conventional layout:

project/
├── features/
│   ├── cart.feature                # Gherkin features
│   ├── steps/
│   │   ├── cart_steps.py            # step implementations
│   │   └── shared_steps.py
│   └── environment.py               # setup/teardown hooks
└── ...

Step 3 - Author a Feature

# features/cart.feature
Feature: Apply promo code at checkout

  Background:
    Given a logged-in user
    And the cart contains 1 of "BOOK-001" at $24.99

  Scenario: Apply valid promo
    When I enter "WELCOME10" in the promo input
    And I click "Apply"
    Then the subtotal updates to $22.49

  Scenario Outline: Promo validation
    When I enter "<code>" in the promo input
    And I click "Apply"
    Then an error appears: "<error>"

    Examples:
      | code      | error                 |
      | EXPIRED50 | This code has expired |
      | NOTREAL   | Code not found        |

Step 4 - Write step implementations

# features/steps/cart_steps.py
from behave import given, when, then
from app.cart import Cart
from app.checkout import CheckoutPage
from tests.fixtures import login_user

@given('a logged-in user')
def step_logged_in_user(context):
    context.user = login_user()
    context.page = CheckoutPage(context.user)

@given('the cart contains {qty:d} of "{sku}" at ${price:f}')
def step_cart_contains(context, qty, sku, price):
    context.cart = Cart()
    context.cart.add_item(sku, qty, price)
    context.page.set_cart(context.cart)

@when('I enter "{code}" in the promo input')
def step_enter_promo(context, code):
    context.page.enter_promo(code)

@when('I click "{label}"')
def step_click(context, label):
    context.page.click(label)

@then('the subtotal updates to ${expected:f}')
def step_subtotal(context, expected):
    assert abs(context.page.get_subtotal() - expected) < 0.01, \
        f"Expected {expected}, got {context.page.get_subtotal()}"

@then('an error appears: "{message}"')
def step_error(context, message):
    assert message in context.page.get_error_message()

The context object carries state across steps within a scenario.

Step 5 - Hooks via environment.py

Per behave-docs, environment.py provides "Environmental Controls":

# features/environment.py
def before_all(context):
    """Once before any scenario runs."""
    context.config.setup_logging()
    context.db = setup_test_database()

def after_all(context):
    """Once after all scenarios finish."""
    context.db.close()

def before_scenario(context, scenario):
    """Before each scenario."""
    context.db.start_transaction()

def after_scenario(context, scenario):
    """After each scenario (use scenario.status to check pass/fail)."""
    context.db.rollback()

def before_tag(context, tag):
    """Before scenarios with a specific tag."""
    if tag == 'requires_browser':
        context.browser = launch_browser()

def after_tag(context, tag):
    if tag == 'requires_browser':
        context.browser.quit()

The hook hierarchy: before_all > before_feature > before_scenario > before_step (and the matching after_*).

Step 6 - Tags + filtering

Per behave-docs, "Controlling Things With Tags" is the filter mechanism:

@critical @regression
Scenario: Apply valid promo
  ...

@wip
Scenario: New checkout flow (work in progress)
  ...

# Run only critical
behave --tags=critical

# Skip wip
behave --tags=~wip

# Combine
behave --tags=critical --tags=~slow

Step 7 - Reporting

# Plain text + JUnit XML for CI
behave --junit --junit-directory reports/junit/

# Per-feature output, no colors
behave --format=plain --no-color > test-results.txt

The JUnit XML feeds junit-xml-analysis (in the qa-test-reporting plugin).

Step 8 - Run

behave                         # all features
behave features/cart.feature   # one feature
behave --tags=@critical         # by tag
behave -i cart                  # match file pattern

Step 9 - pytest-bdd alternative

Per behave-docs, Behave is the canonical Python BDD; the ecosystem also includes pytest-bdd which integrates Gherkin into pytest. Choose:

Behave	pytest-bdd
Standalone runner	pytest plugin
Closer to Cucumber semantics	Reuses pytest fixtures
Better for pure-BDD teams	Better when mixing BDD + xUnit-style tests

Anti-patterns

Anti-pattern	Why it fails	Fix
Mixing fixtures across context and module-level state	Hidden coupling; test order matters.	Use context only; reset per scenario via before_scenario (Step 5).
Step regex too greedy	One step matches multiple Gherkin lines.	Use {var} placeholders + type hints ({qty:d} per Step 4).
before_all setup that fails	All scenarios fail; debugging hard.	Quick smoke check in before_all; fail fast with clear message.
@wip scenarios shipping in CI	Test runner counts them as passes.	behave --tags=~wip in CI (Step 6).
One step file with 200 steps	Hard to navigate; merge conflicts.	Split per-feature: cart_steps.py, checkout_steps.py, etc.

Limitations

• Slower than pytest. Behave's parsing + step matching adds overhead; pytest is faster for non-BDD use.
• No native parallel runner. Use behave-parallel plugin OR shard at CI level via tag filtering.
• Gherkin variations. Some Cucumber features (Rule blocks per Gherkin 6+) have spotty Behave support; verify for the version pinned.

References

• bd - Behave overview: BDD Python-style; step implementations + environment.py + tags; cross-stakeholder collaboration framing.
• cucumber-testing, reqnroll-testing - sibling language wrappers.
• bdd-step-library-curator - keeps step proliferation in check.