Behave

A comprehensive Behavior-Driven Development (BDD) testing framework for Python that enables teams to write tests in natural language style using the Gherkin syntax, backed by Python step implementations. It facilitates collaboration between developers, QA engineers, and non-technical stakeholders by allowing test scenarios to be written in plain English using Given-When-Then statements.

Package Information

• Package Name: behave
• Language: Python
• Installation: pip install behave

Core Imports

import behave

For step definitions:

from behave import given, when, then, step
# Or uppercase aliases:
from behave import Given, When, Then, Step

For fixtures and step matchers:

from behave import fixture, use_fixture, register_type, use_step_matcher

Additional imports for fixtures:

from behave.fixture import use_fixture_by_tag

Basic Usage

# steps/tutorial.py
from behave import given, when, then

@given('we have behave installed')
def step_impl(context):
    pass

@when('we implement a test')
def step_impl(context):
    assert True is not False

@then('behave will test it for us!')
def step_impl(context):
    assert context.failed is False

Feature file (tutorial.feature):

Feature: showing off behave

  Scenario: run a simple test
    Given we have behave installed
    When we implement a test
    Then behave will test it for us!

Running tests:

behave

Architecture

Behave follows the BDD pattern with clear separation of concerns:

• Features: Written in Gherkin syntax describing behaviors in plain English
• Steps: Python implementations of Given/When/Then statements
• Context: Shared state object passed between steps within scenarios
• Hooks: Setup/teardown functions executed at various test phases
• Runner: Test execution engine that processes features and runs steps
• Formatters: Output processors for different reporting formats

Capabilities

Step Definitions

Core decorators for defining test steps that match Gherkin statements. These form the foundation of BDD test implementation, allowing natural language scenarios to be backed by executable Python code.

def given(pattern: str, **kwargs): ...
def when(pattern: str, **kwargs): ...
def then(pattern: str, **kwargs): ...
def step(pattern: str, **kwargs): ...
# Uppercase aliases:
def Given(pattern: str, **kwargs): ...
def When(pattern: str, **kwargs): ...
def Then(pattern: str, **kwargs): ...
def Step(pattern: str, **kwargs): ...

Step Definitions

Fixture System

Reusable setup and teardown functionality for managing test state, database connections, browser instances, and other resources. Fixtures can be scoped to functions, scenarios, features, or the entire test session.

def fixture(func=None, *, scope: str = "function", name: str = None): ...
def use_fixture(fixture_func, context, *args, **kwargs): ...
def use_fixture_by_tag(tag, context, fixture_registry): ...

Fixtures

Step Matchers and Types

Pattern matching and parameter conversion system for extracting and transforming data from step text into Python objects. Supports multiple matching strategies and custom type registration.

def register_type(name: str, func): ...
def use_step_matcher(name: str): ...
def use_default_step_matcher(name: str = None): ...
# Deprecated:
def step_matcher(name: str): ...  # Use use_step_matcher() instead

Matchers and Types

Test Execution Model

Core classes representing BDD constructs including features, scenarios, steps, and execution context. These provide the structural foundation for organizing and running BDD tests.

class Feature: ...
class Scenario: ...
class Step: ...
class Context: ...
class Runner: ...

Test Execution Model

Configuration and CLI

Command-line interface and configuration system for customizing test execution, output formatting, test selection, and runtime behavior. Supports extensive options for different testing environments.

class Configuration: ...
def main(argv: list = None) -> int: ...

Configuration

Output Formatters

Extensible reporting system supporting multiple output formats including plain text, JSON, JUnit XML, and custom formats. Enables integration with CI/CD systems and test reporting tools.

class Formatter: ...
class PlainFormatter(Formatter): ...
class PrettyFormatter(Formatter): ...
class JSONFormatter(Formatter): ...
class JUnitFormatter(Formatter): ...

Output Formatters