behave

library1.3.3pypypi✓ verified 52d ago

behave is a behavior-driven development (BDD) framework for Python, enabling teams to write executable specifications in Gherkin feature files. It supports Gherkin v6, Cucumber-Expressions, and async-steps, allowing for clear, human-readable tests. The current stable version is 1.3.3, with releases typically focusing on bug fixes and incremental feature enhancements, sometimes with pre-releases for larger changes.

testing

pip install behave

github ↗package ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

tested against v1.3.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.287s · 20.7MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 2.2s · import 0.262s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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)

✗ from behave.api.async_step import async_run_called_with_context

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').

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

behave --version

Debug

Known issues

breakingRecursive 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.

affects: >=1.3.2

gotchaPython 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.

affects: 1.3.2

gotchaImportError 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.

affects: 1.3.0, 1.3.1

breakingVersion 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.

affects: >=1.3.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'behave'

The behave library is not installed in the Python environment being used, or the Python interpreter cannot locate the installed package.

fix

Install the behave library using pip: `pip install behave`.

Undefined step

A step in your Gherkin feature file does not have a corresponding Python step definition (a function decorated with @given, @when, or @then) in the 'features/steps' directory, or behave cannot locate the step definition file.

fix

Ensure that a Python step definition function exists with a decorator (e.g., `@given('my step text')`) that exactly matches the Gherkin step. Verify that the step definition file is correctly placed within the 'features/steps' directory and that Python package structure (e.g., `__init__.py` files) is correct if using subdirectories.

ImportError: cannot import name 'given' from 'behave'

This error can occur if you're trying to import step decorators (like `given`, `when`, `then`) directly from the top-level `behave` package, especially with older behave versions or if a linter (like Pylint) is misconfigured and doesn't recognize these dynamically exposed names.

fix

The standard and recommended way to import these decorators is `from behave import given, when, then`. Ensure your `behave` installation is reasonably up-to-date (version 1.2.7 or higher), and if using a linter, configure it to correctly handle behave's imports or suppress the specific error.

AttributeError: 'Context' object has no attribute 'driver'

You are attempting to access an attribute (like 'driver' for a Selenium WebDriver instance) on the behave 'context' object that has not been previously set or is not available within the current scope (e.g., a specific step or hook).

fix

Ensure the attribute is correctly set on the `context` object within the appropriate hook (e.g., `context.driver = webdriver.Chrome()` in `features/environment.py` within `before_scenario` or `before_feature`) and that the attribute name is consistent when being accessed.

ConfigError: No steps directory in []

Behave cannot find the required 'features' directory or the 'steps' subdirectory within it, which is where your feature files and step definitions are expected to reside by default.

fix

Organize your project structure according to behave's conventions: place your feature files in a 'features' directory (e.g., `your_project/features/my_feature.feature`) and your step definitions in a 'steps' subdirectory within 'features' (e.g., `your_project/features/steps/my_steps.py`). If running behave from a different directory, you might need to specify the path explicitly.

Upgrade

Version history

1.3.3latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

claudebot

seranking-bot

ahrefsbot

amazonbot

Resources

githubhttps://github.com/behave/behave ↗

packagehttps://pypi.org/project/behave/ ↗

docshttps://behave.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/behave/behave/blob/main/CHANGES.rst ↗