0
# Behave
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: behave
7
- **Language**: Python
8
- **Installation**: `pip install behave`
9

10
## Core Imports
11

12
```python
13
import behave
14
```
15

16
For step definitions:
17

18
```python
19
from behave import given, when, then, step
20
# Or uppercase aliases:
21
from behave import Given, When, Then, Step
22
```
23

24
For fixtures and step matchers:
25

26
```python
27
from behave import fixture, use_fixture, register_type, use_step_matcher
28
```
29

30
Additional imports for fixtures:
31

32
```python
33
from behave.fixture import use_fixture_by_tag
34
```
35

36
## Basic Usage
37

38
```python
39
# steps/tutorial.py
40
from behave import given, when, then
41

42
@given('we have behave installed')
43
def step_impl(context):
44
    pass
45

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

50
@then('behave will test it for us!')
51
def step_impl(context):
52
    assert context.failed is False
53
```
54

55
Feature file (tutorial.feature):
56
```gherkin
57
Feature: showing off behave
58

59
  Scenario: run a simple test
60
    Given we have behave installed
61
    When we implement a test
62
    Then behave will test it for us!
63
```
64

65
Running tests:
66
```bash
67
behave
68
```
69

70
## Architecture
71

72
Behave follows the BDD pattern with clear separation of concerns:
73

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

81
## Capabilities
82

83
### Step Definitions
84

85
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.
86

87
```python { .api }
88
def given(pattern: str, **kwargs): ...
89
def when(pattern: str, **kwargs): ...
90
def then(pattern: str, **kwargs): ...
91
def step(pattern: str, **kwargs): ...
92
# Uppercase aliases:
93
def Given(pattern: str, **kwargs): ...
94
def When(pattern: str, **kwargs): ...
95
def Then(pattern: str, **kwargs): ...
96
def Step(pattern: str, **kwargs): ...
97
```
98

99
[Step Definitions](./step-definitions.md)
100

101
### Fixture System
102

103
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.
104

105
```python { .api }
106
def fixture(func=None, *, scope: str = "function", name: str = None): ...
107
def use_fixture(fixture_func, context, *args, **kwargs): ...
108
def use_fixture_by_tag(tag, context, fixture_registry): ...
109
```
110

111
[Fixtures](./fixtures.md)
112

113
### Step Matchers and Types
114

115
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.
116

117
```python { .api }
118
def register_type(name: str, func): ...
119
def use_step_matcher(name: str): ...
120
def use_default_step_matcher(name: str = None): ...
121
# Deprecated:
122
def step_matcher(name: str): ...  # Use use_step_matcher() instead
123
```
124

125
[Matchers and Types](./matchers-types.md)
126

127
### Test Execution Model
128

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

131
```python { .api }
132
class Feature: ...
133
class Scenario: ...
134
class Step: ...
135
class Context: ...
136
class Runner: ...
137
```
138

139
[Test Execution Model](./execution-model.md)
140

141
### Configuration and CLI
142

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

145
```python { .api }
146
class Configuration: ...
147
def main(argv: list = None) -> int: ...
148
```
149

150
[Configuration](./configuration.md)
151

152
### Output Formatters
153

154
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.
155

156
```python { .api }
157
class Formatter: ...
158
class PlainFormatter(Formatter): ...
159
class PrettyFormatter(Formatter): ...
160
class JSONFormatter(Formatter): ...
161
class JUnitFormatter(Formatter): ...
162
```
163

164
[Output Formatters](./formatters.md)