0
# Test Decorators
1

2
Comprehensive set of decorators for enhancing test metadata and organization. These decorators allow tests to be annotated with titles, descriptions, labels, links, and organizational information that appears in Allure reports.
3

4
## Capabilities
5

6
### Test Identification and Documentation
7

8
Core decorators for providing human-readable test information and documentation.
9

10
```python { .api }
11
def title(test_title):
12
    """
13
    Set a custom title for the test.
14
    
15
    Parameters:
16
    - test_title (str): The title to display in the report
17
    
18
    Returns:
19
    Function decorator
20
    """
21

22
def description(test_description):
23
    """
24
    Add a description to the test.
25
    
26
    Parameters:
27
    - test_description (str): Plain text description
28
    
29
    Returns:
30
    Function decorator
31
    """
32

33
def description_html(test_description_html):
34
    """
35
    Add an HTML description to the test.
36
    
37
    Parameters:
38
    - test_description_html (str): HTML formatted description
39
    
40
    Returns:
41
    Function decorator
42
    """
43

44
def id(id):
45
    """
46
    Set a unique identifier for the test.
47
    
48
    Parameters:
49
    - id (str): Unique test identifier
50
    
51
    Returns:
52
    Function decorator
53
    """
54
```
55

56
**Usage Examples:**
57

58
```python
59
@allure.title("User Authentication Test")
60
@allure.description("Verifies that users can log in with valid credentials")
61
@allure.id("AUTH-001")
62
def test_user_login():
63
    pass
64

65
@allure.description_html("""
66
<h3>Complex Test Scenario</h3>
67
<ul>
68
    <li>Step 1: Initialize data</li>
69
    <li>Step 2: Execute operation</li>
70
    <li>Step 3: Verify results</li>
71
</ul>
72
""")
73
def test_complex_scenario():
74
    pass
75
```
76

77
### Test Organization and Labeling
78

79
Decorators for organizing tests into hierarchical structures and adding categorical labels.
80

81
```python { .api }
82
def label(label_type, *labels):
83
    """
84
    Add custom labels to the test.
85
    
86
    Parameters:
87
    - label_type (str): Type of label (from LabelType constants)
88
    - *labels: Variable number of label values
89
    
90
    Returns:
91
    Function decorator
92
    """
93

94
def severity(severity_level):
95
    """
96
    Set the test severity level.
97
    
98
    Parameters:
99
    - severity_level (Severity): Severity enum value
100
    
101
    Returns:
102
    Function decorator
103
    """
104

105
def tag(*tags):
106
    """
107
    Add tags to the test for filtering and organization.
108
    
109
    Parameters:
110
    - *tags: Variable number of tag strings
111
    
112
    Returns:
113
    Function decorator
114
    """
115

116
def epic(*epics):
117
    """
118
    Associate test with one or more epics.
119
    
120
    Parameters:
121
    - *epics: Variable number of epic names
122
    
123
    Returns:
124
    Function decorator
125
    """
126

127
def feature(*features):
128
    """
129
    Associate test with one or more features.
130
    
131
    Parameters:
132
    - *features: Variable number of feature names
133
    
134
    Returns:
135
    Function decorator
136
    """
137

138
def story(*stories):
139
    """
140
    Associate test with one or more user stories.
141
    
142
    Parameters:
143
    - *stories: Variable number of story names
144
    
145
    Returns:
146
    Function decorator
147
    """
148
```
149

150
**Usage Examples:**
151

152
```python
153
@allure.severity(allure.severity_level.CRITICAL)
154
@allure.epic("User Management")
155
@allure.feature("Authentication")
156
@allure.story("User Login")
157
@allure.tag("smoke", "regression")
158
def test_critical_login():
159
    pass
160

161
@allure.label("owner", "qa-team")
162
@allure.label("layer", "api")
163
def test_api_endpoint():
164
    pass
165
```
166

167
### Test Suite Organization
168

169
Decorators for organizing tests into suite hierarchies.
170

171
```python { .api }
172
def suite(suite_name):
173
    """
174
    Set the test suite name.
175
    
176
    Parameters:
177
    - suite_name (str): Name of the test suite
178
    
179
    Returns:
180
    Function decorator
181
    """
182

183
def parent_suite(parent_suite_name):
184
    """
185
    Set the parent suite name for hierarchical organization.
186
    
187
    Parameters:
188
    - parent_suite_name (str): Name of the parent suite
189
    
190
    Returns:
191
    Function decorator
192
    """
193

194
def sub_suite(sub_suite_name):
195
    """
196
    Set the sub suite name for detailed organization.
197
    
198
    Parameters:
199
    - sub_suite_name (str): Name of the sub suite
200
    
201
    Returns:
202
    Function decorator
203
    """
204
```
205

206
**Usage Examples:**
207

208
```python
209
@allure.parent_suite("E2E Tests")
210
@allure.suite("Authentication Suite")
211
@allure.sub_suite("Login Tests")
212
def test_user_login():
213
    pass
214
```
215

216
### Links and References
217

218
Decorators for linking tests to external resources like bug trackers, test case management systems, and documentation.
219

220
```python { .api }
221
def link(url, link_type=LinkType.LINK, name=None):
222
    """
223
    Add a link to the test.
224
    
225
    Parameters:
226
    - url (str): URL to link to
227
    - link_type (str): Type of link (from LinkType constants)
228
    - name (str, optional): Display name for the link
229
    
230
    Returns:
231
    Function decorator
232
    """
233

234
def issue(url, name=None):
235
    """
236
    Link to a bug or issue tracker.
237
    
238
    Parameters:
239
    - url (str): URL to the issue
240
    - name (str, optional): Display name for the issue
241
    
242
    Returns:
243
    Function decorator
244
    """
245

246
def testcase(url, name=None):
247
    """
248
    Link to a test case in a test management system.
249
    
250
    Parameters:
251
    - url (str): URL to the test case
252
    - name (str, optional): Display name for the test case
253
    
254
    Returns:
255
    Function decorator
256
    """
257
```
258

259
**Usage Examples:**
260

261
```python
262
@allure.issue("https://jira.company.com/BUG-123", "Login Bug")
263
@allure.testcase("https://testcase.company.com/TC-456", "Login Test Case")
264
@allure.link("https://docs.company.com/auth", "Authentication Docs")
265
def test_login_with_references():
266
    pass
267
```
268

269
### Manual Test Marking
270

271
Decorator for marking tests as manual execution tests.
272

273
```python { .api }
274
def manual(fn):
275
    """
276
    Mark a test as requiring manual execution.
277
    
278
    Parameters:
279
    - fn: The test function to mark
280
    
281
    Returns:
282
    Decorated function
283
    """
284
```
285

286
**Usage Example:**
287

288
```python
289
@allure.manual
290
def test_manual_verification():
291
    """This test requires manual verification of UI elements."""
292
    pass
293
```
294

295
### Dynamic Test Enhancement
296

297
Class providing static methods for modifying test metadata at runtime during test execution.
298

299
```python { .api }
300
class Dynamic:
301
    @staticmethod
302
    def title(test_title):
303
        """Set test title at runtime."""
304
    
305
    @staticmethod  
306
    def description(test_description):
307
        """Add description at runtime."""
308
    
309
    @staticmethod
310
    def description_html(test_description_html):
311
        """Add HTML description at runtime."""
312
    
313
    @staticmethod
314
    def label(label_type, *labels):
315
        """Add labels at runtime."""
316
    
317
    @staticmethod
318
    def severity(severity_level):
319
        """Set severity at runtime."""
320
    
321
    @staticmethod
322
    def epic(*epics):
323
        """Set epics at runtime."""
324
    
325
    @staticmethod
326
    def feature(*features):
327
        """Set features at runtime."""
328
    
329
    @staticmethod
330
    def story(*stories):
331
        """Set stories at runtime."""
332
    
333
    @staticmethod
334
    def tag(*tags):
335
        """Add tags at runtime."""
336
    
337
    @staticmethod
338
    def id(id):
339
        """Set test ID at runtime."""
340
    
341
    @staticmethod
342
    def link(url, link_type=LinkType.LINK, name=None):
343
        """Add link at runtime."""
344
    
345
    @staticmethod
346
    def parameter(name, value, excluded=None, mode=None):
347
        """Add parameter at runtime."""
348
    
349
    @staticmethod
350
    def issue(url, name=None):
351
        """Add issue link at runtime."""
352
    
353
    @staticmethod
354
    def testcase(url, name=None):
355
        """Add test case link at runtime."""
356
    
357
    @staticmethod
358
    def suite(suite_name):
359
        """Set suite at runtime."""
360
    
361
    @staticmethod
362
    def parent_suite(parent_suite_name):
363
        """Set parent suite at runtime."""
364
    
365
    @staticmethod
366
    def sub_suite(sub_suite_name):
367
        """Set sub suite at runtime."""
368
    
369
    @staticmethod
370
    def manual():
371
        """Mark as manual test at runtime."""
372
```
373

374
**Usage Examples:**
375

376
```python
377
def test_dynamic_enhancement():
378
    # Modify test metadata based on runtime conditions
379
    if is_production_environment():
380
        allure.dynamic.severity(allure.severity_level.CRITICAL)
381
        allure.dynamic.tag("production")
382
    
383
    test_data = get_test_data()
384
    allure.dynamic.title(f"Test with data: {test_data['name']}")
385
    allure.dynamic.parameter("test_data", test_data)
386
    
387
    if test_data['type'] == 'regression':
388
        allure.dynamic.story("Regression Testing")
389
```
390

391
## Constants and Enums
392

393
### Severity Levels
394

395
```python { .api }
396
class Severity(str, Enum):
397
    BLOCKER = 'blocker'
398
    CRITICAL = 'critical' 
399
    NORMAL = 'normal'
400
    MINOR = 'minor'
401
    TRIVIAL = 'trivial'
402
```
403

404
### Link Types
405

406
```python { .api }
407
class LinkType:
408
    LINK = 'link'
409
    ISSUE = 'issue'
410
    TEST_CASE = 'tms'
411
```
412

413
### Label Types
414

415
```python { .api }
416
class LabelType(str):
417
    EPIC = 'epic'
418
    FEATURE = 'feature'
419
    STORY = 'story'
420
    PARENT_SUITE = 'parentSuite'
421
    SUITE = 'suite'
422
    SUB_SUITE = 'subSuite'
423
    SEVERITY = 'severity'
424
    THREAD = 'thread'
425
    HOST = 'host'
426
    TAG = 'tag'
427
    ID = 'as_id'
428
    FRAMEWORK = 'framework'
429
    LANGUAGE = 'language'
430
    MANUAL = 'ALLURE_MANUAL'
431
```