0
# Step Definitions
1
2
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.
3
4
## Capabilities
5
6
### Given Step Decorator
7
8
Decorator for defining Given steps that describe the initial context or setup for a scenario. Given steps establish the pre-conditions before testing begins.
9
10
```python { .api }
11
def given(pattern: str, use_step_matcher: str = None):
12
"""
13
Decorator for defining Given steps in BDD scenarios.
14
15
Parameters:
16
- pattern: str, regular expression or parse pattern to match step text
17
- use_step_matcher: str, optional step matcher to use ("parse", "cfparse", "re")
18
19
Returns:
20
Function decorator that registers the step definition
21
"""
22
```
23
24
Usage example:
25
```python
26
@given('I have {count:d} items in my basket')
27
def step_impl(context, count):
28
context.basket_items = count
29
```
30
31
### When Step Decorator
32
33
Decorator for defining When steps that describe actions or events. When steps represent the behavior being tested.
34
35
```python { .api }
36
def when(pattern: str, use_step_matcher: str = None):
37
"""
38
Decorator for defining When steps in BDD scenarios.
39
40
Parameters:
41
- pattern: str, regular expression or parse pattern to match step text
42
- use_step_matcher: str, optional step matcher to use ("parse", "cfparse", "re")
43
44
Returns:
45
Function decorator that registers the step definition
46
"""
47
```
48
49
Usage example:
50
```python
51
@when('I remove {count:d} items from my basket')
52
def step_impl(context, count):
53
context.basket_items -= count
54
```
55
56
### Then Step Decorator
57
58
Decorator for defining Then steps that describe expected outcomes or assertions. Then steps verify that the system behaves as expected.
59
60
```python { .api }
61
def then(pattern: str, use_step_matcher: str = None):
62
"""
63
Decorator for defining Then steps in BDD scenarios.
64
65
Parameters:
66
- pattern: str, regular expression or parse pattern to match step text
67
- use_step_matcher: str, optional step matcher to use ("parse", "cfparse", "re")
68
69
Returns:
70
Function decorator that registers the step definition
71
"""
72
```
73
74
Usage example:
75
```python
76
@then('I should have {count:d} items in my basket')
77
def step_impl(context, count):
78
assert context.basket_items == count
79
```
80
81
### Generic Step Decorator
82
83
Generic step decorator that can match any step type (Given, When, or Then). Useful for reusable steps that apply to multiple contexts.
84
85
```python { .api }
86
def step(pattern: str, use_step_matcher: str = None):
87
"""
88
Generic step decorator for steps that can match any type.
89
90
Parameters:
91
- pattern: str, regular expression or parse pattern to match step text
92
- use_step_matcher: str, optional step matcher to use ("parse", "cfparse", "re")
93
94
Returns:
95
Function decorator that registers the step definition
96
"""
97
```
98
99
Usage example:
100
```python
101
@step('I wait {seconds:d} seconds')
102
def step_impl(context, seconds):
103
time.sleep(seconds)
104
```
105
106
### Alternative Step Decorators
107
108
Behave also provides uppercase aliases for the step decorators for stylistic preferences.
109
110
```python { .api }
111
# Uppercase aliases (identical functionality to lowercase versions)
112
def Given(pattern: str, use_step_matcher: str = None): ...
113
def When(pattern: str, use_step_matcher: str = None): ...
114
def Then(pattern: str, use_step_matcher: str = None): ...
115
def Step(pattern: str, use_step_matcher: str = None): ...
116
```
117
118
Usage example:
119
```python
120
from behave import Given, When, Then
121
122
@Given('I have an account')
123
def step_impl(context):
124
context.account = Account()
125
126
@When('I log in')
127
def step_impl(context):
128
context.account.login()
129
130
@Then('I should be authenticated')
131
def step_impl(context):
132
assert context.account.is_authenticated()
133
```
134
135
### Async Step Support
136
137
Behave natively supports async step functions since version 1.4.0. Simply use the regular step decorators with async functions.
138
139
Usage example:
140
```python
141
@when('I make an async API call')
142
async def step_impl(context):
143
response = await context.http_client.get('/api/data')
144
context.response = response
145
```
146
147
## Step Function Context
148
149
All step functions receive a `context` parameter that provides shared state and utilities:
150
151
### Context Object
152
153
```python { .api }
154
class Context:
155
"""
156
Execution context shared between steps within a scenario.
157
158
Attributes:
159
- feature: Current Feature object
160
- scenario: Current Scenario object
161
- table: Table data attached to current step (if any)
162
- text: Multi-line text attached to current step (if any)
163
- failed: Boolean indicating if any step has failed
164
- config: Configuration object with behave settings
165
- tags: Set of tags from current scenario and feature
166
"""
167
```
168
169
The context object allows steps to:
170
- Share data between steps in a scenario
171
- Access step data (tables and multi-line text)
172
- Check execution status
173
- Access configuration settings
174
- Use tag-based conditional logic
175
176
## Step Data
177
178
Steps can access additional data attached to them in feature files:
179
180
### Table Data
181
```python
182
# In feature file:
183
# When I process the following data:
184
# | name | age |
185
# | Alice | 25 |
186
# | Bob | 30 |
187
188
@when('I process the following data')
189
def step_impl(context):
190
for row in context.table:
191
name = row['name']
192
age = int(row['age'])
193
# Process row data
194
```
195
196
### Multi-line Text
197
```python
198
# In feature file:
199
# When I submit the following JSON:
200
# """
201
# {"user": "test", "action": "login"}
202
# """
203
204
@when('I submit the following JSON')
205
def step_impl(context):
206
import json
207
data = json.loads(context.text)
208
# Process JSON data
209
```