0
# Utility Functions
1

2
Helper functions for processing Behave scenarios, steps, and extracting metadata for Allure reports. These utilities handle status conversion, parameter extraction, naming conventions, and test organization.
3

4
## Capabilities
5

6
### Scenario Processing Functions
7

8
Functions for extracting and processing information from Behave scenario objects:
9

10
```python { .api }
11
def scenario_name(scenario):
12
    """
13
    Extract display name from scenario.
14
    
15
    Parameters:
16
    - scenario: Behave scenario object
17
    
18
    Returns:
19
    str: Scenario name or scenario keyword if name is empty
20
    """
21

22
def scenario_history_id(scenario):
23
    """
24
    Generate unique history ID for scenario tracking across test runs.
25
    
26
    Parameters:
27
    - scenario: Behave scenario object
28
    
29
    Returns:
30
    str: MD5 hash of feature name, scenario name, and parameters
31
    """
32

33
def scenario_parameters(scenario):
34
    """
35
    Extract parameters from scenario outline table rows.
36
    
37
    Parameters:
38
    - scenario: Behave scenario object with optional _row attribute
39
    
40
    Returns:
41
    list[Parameter] | None: List of Parameter objects or None if no table
42
    """
43

44
def scenario_links(scenario, issue_pattern, link_pattern):
45
    """
46
    Extract links from scenario and feature tags.
47
    
48
    Parameters:
49
    - scenario: Behave scenario object
50
    - issue_pattern (str): Pattern for formatting issue links (e.g., "https://jira.com/browse/{}")
51
    - link_pattern (str): Pattern for formatting custom links
52
    
53
    Returns:
54
    filter: Filtered iterator of Link objects from parsed tags
55
    """
56

57
def scenario_labels(scenario):
58
    """
59
    Extract labels from scenario and feature tags.
60
    
61
    Parameters:
62
    - scenario: Behave scenario object
63
    
64
    Returns:
65
    list[Label]: Deduplicated list of Label objects including default severity
66
    """
67

68
def scenario_status(scenario):
69
    """
70
    Determine overall scenario status from step results.
71
    
72
    Parameters:
73
    - scenario: Behave scenario object with all_steps attribute
74
    
75
    Returns:
76
    Status: PASSED if all steps passed, otherwise first failing step status
77
    """
78

79
def scenario_status_details(scenario):
80
    """
81
    Get detailed status information from first failing step.
82
    
83
    Parameters:
84
    - scenario: Behave scenario object with all_steps attribute
85
    
86
    Returns:
87
    StatusDetails | None: Status details from first failing step or None
88
    """
89
```
90

91
### Step Processing Functions
92

93
Functions for processing Behave step execution results:
94

95
```python { .api }
96
def step_status(result):
97
    """
98
    Convert Behave step result to Allure status.
99
    
100
    Parameters:
101
    - result: Behave result object with status and exception attributes
102
    
103
    Returns:
104
    Status: Corresponding Allure Status enum value
105
    """
106

107
def step_status_details(result):
108
    """
109
    Extract detailed status information from step result.
110
    
111
    Parameters:
112
    - result: Behave result object with exception and traceback info
113
    
114
    Returns:
115
    StatusDetails | None: Detailed error information or implementation snippets
116
    """
117

118
def step_table(step):
119
    """
120
    Convert step table to CSV format for attachment.
121
    
122
    Parameters:
123
    - step: Behave step object with table attribute
124
    
125
    Returns:
126
    str: CSV formatted table with headers and rows
127
    """
128
```
129

130
### Status Conversion Functions
131

132
Functions for converting Python exceptions and Behave statuses to Allure format:
133

134
```python { .api }
135
def get_status(exception):
136
    """
137
    Convert Python exception to Allure status.
138
    
139
    Parameters:
140
    - exception: Python exception object or None
141
    
142
    Returns:
143
    Status: FAILED for AssertionError, BROKEN for other exceptions, PASSED for None
144
    """
145

146
def get_status_details(exc_type, exception, exc_traceback):
147
    """
148
    Create StatusDetails from exception information.
149
    
150
    Parameters:
151
    - exc_type: Exception type
152
    - exception: Exception instance
153
    - exc_traceback: Exception traceback
154
    
155
    Returns:
156
    StatusDetails | None: Formatted exception details or None
157
    """
158
```
159

160
### Test Organization Functions
161

162
Functions for generating test names and organizing test results:
163

164
```python { .api }
165
def get_fullname(scenario):
166
    """
167
    Generate full test name combining feature and scenario names.
168
    
169
    Parameters:
170
    - scenario: Behave scenario object with feature reference
171
    
172
    Returns:
173
    str: Formatted as "Feature Name: Scenario Name" (without parameters)
174
    """
175

176
def get_title_path(scenario):
177
    """
178
    Generate hierarchical title path for test organization.
179
    
180
    Parameters:
181
    - scenario: Behave scenario object with filename and feature info
182
    
183
    Returns:
184
    list[str]: Path components including directory structure and feature name
185
    """
186

187
def get_hook_name(name, parameters):
188
    """
189
    Format hook names for display in reports.
190
    
191
    Parameters:
192
    - name (str): Hook name (e.g., "before_tag", "after_scenario")
193
    - parameters (dict): Hook parameters, may contain tag information
194
    
195
    Returns:
196
    str: Formatted hook name with tag information if applicable
197
    """
198
```
199

200
### Test Plan Functions
201

202
Functions for handling Allure test plan integration:
203

204
```python { .api }
205
def is_planned_scenario(scenario, test_plan):
206
    """
207
    Check if scenario should run based on Allure test plan.
208
    
209
    Parameters:
210
    - scenario: Behave scenario object
211
    - test_plan: Allure test plan data or None
212
    
213
    Returns:
214
    None: Modifies scenario in-place, skipping it if not in test plan
215
    
216
    Side Effects:
217
    - Calls scenario.skip() with TEST_PLAN_SKIP_REASON if not planned
218
    - Uses scenario fullname and @allure.id labels for matching
219
    """
220
```
221

222
## Constants
223

224
```python { .api }
225
TEST_PLAN_SKIP_REASON = "Not in allure test plan"
226
"""Constant string used as skip reason for test plan filtering."""
227

228
STATUS = {
229
    'passed': Status.PASSED,
230
    'failed': Status.FAILED,
231
    'skipped': Status.SKIPPED,
232
    'untested': Status.SKIPPED,
233
    'undefined': Status.BROKEN
234
}
235
"""Mapping dictionary from Behave status strings to Allure Status enum values."""
236
```
237

238
## Usage Examples
239

240
### Custom Status Processing
241

242
```python
243
from allure_behave.utils import step_status, step_status_details
244

245
def custom_step_processor(step_result):
246
    status = step_status(step_result)
247
    details = step_status_details(step_result)
248
    
249
    if status == Status.BROKEN:
250
        # Handle broken steps specially
251
        print(f"Broken step: {details.message}")
252
    
253
    return status, details
254
```
255

256
### Scenario Metadata Extraction
257

258
```python
259
from allure_behave.utils import (
260
    scenario_name, scenario_parameters, 
261
    scenario_labels, scenario_links
262
)
263

264
def analyze_scenario(scenario):
265
    name = scenario_name(scenario)
266
    params = scenario_parameters(scenario)
267
    labels = scenario_labels(scenario) 
268
    links = list(scenario_links(scenario, 
269
                               issue_pattern="https://jira.com/browse/{}", 
270
                               link_pattern="https://wiki.com/{}"))
271
    
272
    print(f"Scenario: {name}")
273
    if params:
274
        print(f"Parameters: {[p.name + '=' + p.value for p in params]}")
275
    print(f"Labels: {[l.name + '=' + l.value for l in labels]}")
276
    print(f"Links: {[l.url for l in links]}")
277
```
278

279
### Test Organization
280

281
```python
282
from allure_behave.utils import get_fullname, get_title_path
283

284
def organize_test_results(scenario):
285
    fullname = get_fullname(scenario)
286
    title_path = get_title_path(scenario)
287
    
288
    # Create hierarchical test organization
289
    return {
290
        'id': fullname,
291
        'path': title_path,
292
        'category': title_path[-1]  # Feature name
293
    }
294
```
295

296
### Custom Test Plan Processing
297

298
```python
299
from allure_behave.utils import is_planned_scenario
300

301
def apply_custom_test_plan(scenarios, test_plan):
302
    """Apply test plan to scenarios with custom logic."""
303
    for scenario in scenarios:
304
        # Apply standard test plan logic
305
        is_planned_scenario(scenario, test_plan)
306
        
307
        # Add custom filtering logic
308
        if hasattr(scenario, 'tags'):
309
            if 'slow' in scenario.tags and not os.getenv('RUN_SLOW_TESTS'):
310
                scenario.skip(reason="Slow tests disabled")
311
```
312

313
## Type Definitions
314

315
```python { .api }
316
from allure_commons.model2 import Parameter, Label, Link, StatusDetails, Status
317

318
class Parameter:
319
    """Test parameter with name and value."""
320
    name: str
321
    value: str
322

323
class Label:
324
    """Test label for categorization and filtering."""  
325
    name: str
326
    value: str
327

328
class Link:
329
    """External link associated with test."""
330
    type: str
331
    url: str
332
    name: str
333

334
class StatusDetails:
335
    """Detailed test/step status information."""
336
    message: str
337
    trace: str
338

339
class Status:
340
    """Allure test status enumeration."""
341
    PASSED = "passed"
342
    FAILED = "failed" 
343
    BROKEN = "broken"
344
    SKIPPED = "skipped"
345
```