0
# Test Execution Model
1
2
Core classes representing BDD constructs including features, scenarios, steps, and execution context. These provide the structural foundation for organizing and running BDD tests.
3
4
## Capabilities
5
6
### Feature Class
7
8
Represents a feature file containing scenarios, background steps, and feature metadata. Features are the top-level containers in BDD testing.
9
10
```python { .api }
11
class Feature:
12
"""
13
Container for scenarios, background, and feature metadata.
14
15
Attributes:
16
- name: str, feature name from feature file
17
- description: str, feature description text
18
- scenarios: list, collection of Scenario objects
19
- background: Background, common steps for all scenarios (optional)
20
- tags: list, feature-level tags
21
- filename: str, path to feature file
22
- language: str, natural language used (default: "en")
23
- line: int, line number where feature starts
24
25
Methods:
26
- run(runner): Execute the feature with given runner
27
- should_run(config): Check if feature should run based on configuration
28
"""
29
```
30
31
### Scenario Class
32
33
Represents a scenario or scenario outline with steps and metadata. Scenarios define specific test cases within a feature.
34
35
```python { .api }
36
class Scenario:
37
"""
38
Container for steps and scenario metadata.
39
40
Attributes:
41
- name: str, scenario name
42
- description: str, scenario description text
43
- steps: list, collection of Step objects
44
- tags: list, scenario-level tags (includes feature tags)
45
- feature: Feature, parent feature object
46
- line: int, line number where scenario starts
47
- status: Status, execution status (passed/failed/skipped/undefined)
48
- skip_reason: str, reason for skipping (if skipped)
49
50
Methods:
51
- run(runner): Execute the scenario with given runner
52
- should_run(config): Check if scenario should run based on tags/configuration
53
"""
54
```
55
56
### Scenario Outline Class
57
58
Represents a parameterized scenario with example tables. Scenario outlines enable data-driven testing with multiple parameter combinations.
59
60
```python { .api }
61
class ScenarioOutline:
62
"""
63
Parameterized scenario with example tables.
64
65
Attributes:
66
- name: str, scenario outline name
67
- description: str, scenario outline description
68
- steps: list, template Step objects with parameters
69
- examples: list, Example objects containing parameter tables
70
- tags: list, scenario outline tags
71
- feature: Feature, parent feature object
72
73
Methods:
74
- run(runner): Execute all example combinations
75
- build_scenarios(): Generate individual scenarios from examples
76
"""
77
```
78
79
### Step Class
80
81
Represents an individual Given/When/Then step in a scenario with associated data and execution status.
82
83
```python { .api }
84
class Step:
85
"""
86
Individual Given/When/Then step.
87
88
Attributes:
89
- step_type: str, step type ("given", "when", "then", "and", "but")
90
- name: str, step text without step keyword
91
- text: str, multi-line text attached to step (optional)
92
- table: Table, tabular data attached to step (optional)
93
- line: int, line number where step appears
94
- status: Status, execution status
95
- duration: float, execution time in seconds
96
- error_message: str, error details if step failed
97
- match: Match, matched step definition details
98
99
Methods:
100
- run(runner, context): Execute the step
101
- should_run(config): Check if step should run
102
"""
103
```
104
105
### Background Class
106
107
Represents background steps that run before each scenario in a feature. Background provides common setup steps.
108
109
```python { .api }
110
class Background:
111
"""
112
Common steps executed before each scenario.
113
114
Attributes:
115
- name: str, background name (optional)
116
- description: str, background description
117
- steps: list, collection of Step objects
118
- line: int, line number where background starts
119
120
Methods:
121
- run(runner, context): Execute background steps
122
"""
123
```
124
125
### Context Class
126
127
Execution context object that provides shared state and utilities for steps. The context is passed to every step function and hook.
128
129
```python { .api }
130
class Context:
131
"""
132
Shared state and utilities for steps within a scenario.
133
134
Attributes:
135
- feature: Feature, current feature being executed
136
- scenario: Scenario, current scenario being executed
137
- table: Table, table data from current step (if any)
138
- text: str, multi-line text from current step (if any)
139
- failed: bool, whether any step in scenario has failed
140
- config: Configuration, behave configuration object
141
- tags: set, combined tags from feature and scenario
142
- aborted: bool, whether execution was aborted
143
- log_capture: StringIO, captured log output
144
- stdout_capture: StringIO, captured stdout
145
- stderr_capture: StringIO, captured stderr
146
147
Methods:
148
- execute_steps(steps_text): Execute additional steps dynamically
149
- add_cleanup(cleanup_func): Register cleanup function
150
"""
151
```
152
153
### Runner Class
154
155
Main test execution engine that processes features and runs scenarios and steps.
156
157
```python { .api }
158
class Runner:
159
"""
160
Main test runner that executes features and scenarios.
161
162
Attributes:
163
- config: Configuration, behave configuration
164
- features: list, features to execute
165
- hooks: dict, registered hook functions
166
- formatters: list, output formatters
167
- step_registry: StepRegistry, registered step definitions
168
169
Methods:
170
- run(): Execute all features and return success status
171
- run_feature(feature): Execute a single feature
172
- run_scenario(scenario): Execute a single scenario
173
- run_step(step): Execute a single step
174
- setup_capture(): Initialize output capture
175
- teardown_capture(): Finalize output capture
176
"""
177
```
178
179
## Data Models
180
181
### Table Class
182
183
Represents tabular data attached to steps, providing structured access to table rows and columns.
184
185
```python { .api }
186
class Table:
187
"""
188
Tabular data attached to steps.
189
190
Attributes:
191
- headings: list, column headers
192
- rows: list, Row objects representing table data
193
194
Methods:
195
- assert_equals(expected_table): Assert table equality
196
- require_column(column_name): Ensure column exists
197
- require_columns(column_names): Ensure multiple columns exist
198
"""
199
```
200
201
### Row Class
202
203
Represents a single row in a step table with column access methods.
204
205
```python { .api }
206
class Row:
207
"""
208
Single row in a step table.
209
210
Attributes:
211
- cells: list, raw cell values
212
- headings: list, column headers
213
214
Methods:
215
- get(column, default=None): Get value by column name
216
- as_dict(): Convert row to dictionary
217
- __getitem__(column): Get value by column name or index
218
"""
219
```
220
221
### Tag Class
222
223
Represents scenario and feature tags used for filtering and organization.
224
225
```python { .api }
226
class Tag:
227
"""
228
Tag metadata for filtering and organization.
229
230
Attributes:
231
- name: str, tag name (without @ symbol)
232
- line: int, line number where tag appears
233
"""
234
```
235
236
## Status Enumeration
237
238
Execution status constants for steps, scenarios, and features.
239
240
```python { .api }
241
class Status:
242
"""
243
Execution status enumeration.
244
245
Values:
246
- passed: Step/scenario executed successfully
247
- failed: Step/scenario failed with error
248
- skipped: Step/scenario was skipped
249
- undefined: Step definition not found
250
- executing: Currently executing (internal use)
251
"""
252
```
253
254
## Hook Integration
255
256
The execution model integrates with behave's comprehensive hook system:
257
258
### Execution Flow Hooks
259
```python
260
def before_all(context):
261
"""Called once before all features"""
262
263
def before_feature(context, feature):
264
"""Called before each feature"""
265
266
def before_scenario(context, scenario):
267
"""Called before each scenario"""
268
269
def before_step(context, step):
270
"""Called before each step"""
271
272
def after_step(context, step):
273
"""Called after each step"""
274
275
def after_scenario(context, scenario):
276
"""Called after each scenario"""
277
278
def after_feature(context, feature):
279
"""Called after each feature"""
280
281
def after_all(context):
282
"""Called once after all features"""
283
```
284
285
### Tag-based Hooks
286
```python
287
def before_tag(context, tag):
288
"""Called for scenarios with specific tags"""
289
290
def after_tag(context, tag):
291
"""Called after scenarios with specific tags"""
292
```
293
294
## Example Usage Patterns
295
296
### Accessing Step Data
297
```python
298
@when('I process the following data')
299
def step_impl(context):
300
if context.table:
301
for row in context.table:
302
name = row['name']
303
value = row['value']
304
# Process table data
305
306
if context.text:
307
# Process multi-line text
308
lines = context.text.split('\n')
309
```
310
311
### Scenario State Management
312
```python
313
@given('I initialize the test environment')
314
def step_impl(context):
315
context.test_data = {}
316
context.resources = []
317
318
@when('I perform an action')
319
def step_impl(context):
320
# Access shared state
321
result = perform_action(context.test_data)
322
context.result = result
323
324
@then('the result should be correct')
325
def step_impl(context):
326
assert context.result == expected_value
327
```
328
329
### Dynamic Step Execution
330
```python
331
@when('I execute a complex workflow')
332
def step_impl(context):
333
# Execute additional steps dynamically
334
context.execute_steps('''
335
Given I have valid credentials
336
When I authenticate with the service
337
Then I should be authenticated
338
''')
339
```