behave (BDD Framework)

Warnings

• breaking Recursive discovery and import of steps directories is disabled by default starting from v1.3.2. Nested `steps` directories under the primary `steps` directory will no longer be automatically scanned.
  Fix: If you relied on nested `steps` directories, you must explicitly enable `recursive_steps_import` in your configuration (e.g., `behave.ini`). The recommended best practice is to put Python packages or step-libraries on the Python search path, not directly in nested `steps` directories, to avoid relative import issues.
• gotcha Python 2.7 support was temporarily broken in `v1.3.2` due to an oversight.
  Fix: If you are using Python 2.7, ensure you upgrade to `v1.3.3` or later to restore compatibility. Users on Python 3.x were unaffected.
• gotcha ImportError for `asynccontextmanager` in Python 3.6 could occur with `v1.3.0` and `v1.3.1`.
  Fix: This issue was fixed in `v1.3.1` (although the changelog mentions it for 1.3.1 and 1.3.0). Ensure you are on `v1.3.1` or later if you encounter this when using Python 3.6, especially with async features.
• breaking Version 1.3.0 introduced Gherkin v6, native Cucumber-Expressions, and native async-steps support.
  Fix: While these are powerful new features, migrating older projects to leverage them might require updating Gherkin syntax or step definitions. Old Gherkin syntax and 'parse'/'re' matchers generally remain compatible, but for new features, new syntax and step matchers (like `use_step_matcher('cucumber_expressions')`) will be required.

Install

• pip install behave Install behave

Imports

• given, when, then

  from behave import given, when, then

  Standard decorators for defining steps in Python step definitions.
• step

  from behave import step

  A generic step decorator for defining steps without specific 'Given', 'When', 'Then' keywords.
• before_all, after_all, before_scenario, after_scenario, etc.

  from behave import * # in environment.py (common practice, but specific imports are also fine)

  Hook functions (e.g., `before_feature`, `after_step`) are typically defined in `environment.py` and automatically discovered. Specific imports like `async_run_called_with_context` are for advanced async step handling, not general use.
• use_step_matcher

  from behave import use_step_matcher

  Used to explicitly set the step matcher (e.g., 're' for regex, 'parse' for parsing, 'cfparse' for composite, 'cucumber_expressions').

Quickstart

This quickstart demonstrates how to create a simple feature file and corresponding step definitions using behave. It covers defining Gherkin steps with parameter parsing and basic assertions. Organize your files as shown, then run `behave` from the project root.

# Create the following file structure in your project root:
#
# ./
# ├── features/
# │   ├── example.feature
# │   └── steps/
# │       └── example_steps.py
# └── (run 'behave' from this root directory)

# --- features/example.feature ---
# Feature: Basic addition
#   As a calculator user
#   I want to be able to add numbers
#   So that I can get the sum
#
#   Scenario: Add two numbers
#     Given I have the numbers 5 and 3
#     When I add them
#     Then the result should be 8

# --- features/steps/example_steps.py ---
from behave import given, when, then

@given('I have the numbers {num1:d} and {num2:d}')
def step_impl(context, num1, num2):
    context.num1 = num1
    context.num2 = num2

@when('I add them')
def step_impl(context):
    context.result = context.num1 + context.num2

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

# To run this example:
# 1. Create the files as shown above.
# 2. Navigate to your project's root directory (containing the 'features' folder) in your terminal.
# 3. Execute the behave command:
#    $ behave