behave.readthedocs.io No paid content found

What is behave?

behave is a Behaviour-Driven Development (BDD) framework for Python, documented at behave documentation. It lets teams describe application behaviour in plain-language scenarios and then execute those scenarios as automated tests.

How it works

Scenarios are written in Gherkin syntax, using keywords such as Feature, Scenario, Given, When, and Then. Each step is linked to a small Python function called a step implementation. When the test run starts, behave matches scenario steps to those functions and reports whether each passes, fails, or is undefined.

Who uses it

• Developers who want tests tied to readable requirements.
• Testers and QA engineers building acceptance or regression suites.
• Product owners and business analysts who can read, review, or help write scenarios without reading Python.
• Teams practicing collaboration, where scenarios act as a shared description of expected behaviour.

Trade-offs

The plain-language layer improves communication and documentation, but it adds a step-definition layer to maintain. Simple unit tests are often quicker to write directly; behave is typically better suited to acceptance tests and end-to-end behaviour where shared understanding matters. It also works alongside other Python test tools rather than replacing them entirely.

What is behave used for?

behave documentation is the official documentation for behave, a Python framework for Behavior-Driven Development (BDD).

What behave is used for

behave lets teams write tests in plain-language scenarios that describe how software should behave from a user's perspective. These scenarios use a Gherkin-style syntax with keywords such as Feature, Scenario, Given, When, and Then. Each step is backed by a Python function, so the human-readable description stays connected to executable code.

Typical uses include:

• Acceptance testing — verifying that a feature meets business requirements.
• Collaboration — giving developers, testers, and non-programmers a shared, readable specification.
• Regression testing — re-running scenarios to catch behavior that breaks after changes.
• Living documentation — scenario files that double as up-to-date descriptions of system behavior.

Who it suits

It is suited to Python teams that want BDD-style tests and are comfortable maintaining step definitions alongside test scenarios. Because scenarios are written in near-natural language, they can be reviewed by product owners or analysts, though someone still needs to implement and maintain the underlying Python steps.

Trade-offs

The plain-language layer improves communication and readability, but it adds a maintenance cost: step definitions must be kept in sync with scenarios, and overly verbose feature files can become harder to manage than straightforward unit tests. For small or purely technical tests, a conventional Python test framework may be simpler.

How do I install behave?

To install behave, the Python behavior-driven development (BDD) framework, use pip, Python's standard package installer.

Basic installation

Run this in your terminal or command prompt:

pip install behave

If you have multiple Python versions, target a specific one:

python3 -m pip install behave

Recommended: use a virtual environment

Installing into a per-project virtual environment avoids conflicts with other packages:

python3 -m venv venv
source venv/bin/activate   # macOS/Linux
venv\Scripts\activate      # Windows
pip install behave

Verify the install

Check the version from the command line:

behave --version

You can also confirm the package is present:

pip show behave

Who this suits

This approach fits developers and testers already comfortable with Python tooling. If you are new to Python packaging, the virtual-environment route is the safer habit, since behave is a library you will usually run alongside a test project rather than globally.

Trade-offs to note

A global pip install is quickest but can clash with system-managed packages on some Linux distributions. Using pipx is an option if you only need the command-line runner, though behave is more commonly used as a project dependency.

The official documentation at behave documentation covers installation details and usage beyond this basic setup.

What are the key features of behave?

Behave is a Python framework for Behaviour-Driven Development (BDD). It lets teams describe application behaviour in plain-language Gherkin files and connect each step to Python code.

Key features

• Gherkin feature files: Scenarios use Feature, Scenario, Given, When and Then keywords, so non-programmers can read and review them.
• Step definitions: Decorators such as @given, @when and @then map phrases to Python functions, keeping test logic separate from the specification.
• Scenario outlines and tables: Data-driven scenarios and tabular inputs reduce duplication across similar cases.
• Hooks and environment configuration: before_all, after_scenario and similar hooks allow setup and teardown at chosen points in the run.
• Tags: Scenarios can be tagged and selectively included or excluded, which is useful for smoke suites or slow tests.
• Multiple formatters: Output can be rendered in ways suited to consoles, files or integration with other reporting tools.
• Command-line runner: Tests are launched with the behave command, and configuration can live in files rather than long command lines.

Typical audience and trade-offs

It suits teams that want executable specifications shared between developers, testers and business stakeholders. The plain-language layer improves communication, but it adds maintenance overhead: step definitions must stay in sync with feature files, and poorly written scenarios can become verbose. It is generally a good fit for Python projects already comfortable with pytest-style tooling, though some teams prefer lighter test libraries for unit-level work.

How do I write a feature file in behave?

Feature files in behave use Gherkin syntax, a plain-text format that describes behavior in business-readable language. Each file has a .feature extension and typically begins with a Feature: line, followed by an optional description and one or more scenarios.

H3 Basic structure

A minimal feature file contains:

• Feature: — a short title describing the functionality under test
• Scenario: (or Scenario Outline:) — a single concrete example
• Given, When, Then — steps that set up context, perform an action, and verify an outcome
• And / But — continue the previous step type for readability

H3 Example

Feature: User login

  Scenario: Successful login
    Given a registered user
    When the user submits valid credentials
    Then the dashboard is displayed

Steps map to Python functions in a steps/ directory, decorated with matching @given, @when, and @then. The text after the keyword is matched against step definitions, so wording matters.

H3 Scenario Outlines and tables

Use Scenario Outline: with an Examples: table to run the same steps with multiple data rows. Data tables and docstrings can pass structured or multi-line arguments to steps.

H3 Practical notes

Feature files are suited to teams that want tests readable by non-programmers, such as product owners or QA staff. The trade-off is that step definitions add an extra layer compared with plain unit tests. Keep scenarios focused on one behavior each and avoid technical detail in step text.

The official documentation at behave documentation covers Gherkin syntax, step matching, and environment configuration in more depth.

How do I run behave tests from the command line?

To run behave tests, you invoke the behave command from your project's root directory, where the features/ directory lives. The tool discovers feature files automatically, so a bare behave run executes everything it finds.

Basic invocation and targeting

• Run everything: behave
• Run one feature file: behave features/login.feature
• Run a single scenario by name: behave --name "successful login"
• Run by tag: behave --tags=@smoke or exclude with --tags=-@slow

Useful options

• --format (or -f) selects output style, such as plain, pretty or json.
• --outfile writes results to a file rather than the console.
• --no-capture lets print statements and logs appear live, which helps when debugging.
• --stop halts after the first failure.
• --dry-run checks step matching without executing step code.
• --define passes userdata values into your steps.

Practical notes

Configuration can also live in a behave.ini, tox.ini or .behaverc file, so command-line flags typically override those defaults. Exit codes matter for CI: a non-zero status signals failures, letting build pipelines react automatically.

The official documentation at behave documentation covers the full option list, tag expressions and configuration files. This approach suits teams practising behaviour-driven development who want readable, executable specifications run from a terminal or continuous integration job.