0
# Test Metadata
1

2
Add rich metadata to tests using pytest markers for enhanced categorization, organization, and reporting in the Allure interface. This enables better test organization, filtering, and comprehensive test documentation.
3

4
## Capabilities
5

6
### Test Labels
7

8
Add categorical labels to tests for organization, filtering, and reporting purposes.
9

10
```python { .api }
11
@pytest.mark.allure_label(*labels, label_type=str)
12
    """
13
    Add one or more labels of a specific type to a test.
14
    
15
    Parameters:
16
    - *labels: One or more label values
17
    - label_type: Type of label (severity, feature, story, epic, etc.)
18
    
19
    Usage:
20
    @pytest.mark.allure_label("critical", label_type="severity")
21
    @pytest.mark.allure_label("login", "logout", label_type="feature")
22
    """
23
```
24

25
### Test Links
26

27
Associate tests with external resources like bug trackers, test management systems, or documentation.
28

29
```python { .api }
30
@pytest.mark.allure_link(url, link_type=str, name=str)
31
    """
32
    Add a link to an external resource.
33
    
34
    Parameters:
35
    - url: Full URL or short reference (if link pattern configured)
36
    - link_type: Type of link ("issue", "tms", "test_case", etc.)  
37
    - name: Display name for the link
38
    
39
    Usage:
40
    @pytest.mark.allure_link("https://jira.example.com/PROJ-123", 
41
                           link_type="issue", name="Bug Report")
42
    @pytest.mark.allure_link("PROJ-123", link_type="issue", name="Bug Report")  # With pattern
43
    """
44
```
45

46
### Test Descriptions
47

48
Add detailed descriptions to tests for better documentation and reporting.
49

50
```python { .api }
51
@pytest.mark.allure_description(description)
52
    """
53
    Add a text description to a test.
54
    
55
    Parameters:
56
    - description: Text description of the test
57
    
58
    Note: Test docstrings are automatically used as descriptions if no marker is present.
59
    
60
    Usage:
61
    @pytest.mark.allure_description("Verify user authentication with valid credentials")
62
    """
63

64
@pytest.mark.allure_description_html(html_description)
65
    """
66
    Add an HTML description to a test.
67
    
68
    Parameters:
69
    - html_description: HTML formatted description
70
    
71
    Usage:
72
    @pytest.mark.allure_description_html("<h3>Test Steps</h3><ol><li>Login</li><li>Navigate</li></ol>")
73
    """
74
```
75

76
## Standard Label Types
77

78
### Severity Labels
79

80
```python
81
import allure
82

83
@allure.severity(allure.severity_level.BLOCKER)    # Highest priority
84
@allure.severity(allure.severity_level.CRITICAL)   # High priority  
85
@allure.severity(allure.severity_level.NORMAL)     # Standard priority (default)
86
@allure.severity(allure.severity_level.MINOR)      # Low priority
87
@allure.severity(allure.severity_level.TRIVIAL)    # Lowest priority
88
def test_example():
89
    pass
90
```
91

92
### BDD Labels
93

94
```python
95
import allure
96

97
@allure.epic("E-commerce Platform")           # High-level business capability
98
@allure.feature("User Authentication")        # Product feature
99
@allure.story("User Login Process")          # User story
100
def test_user_login():
101
    pass
102
```
103

104
### Test Organization Labels
105

106
```python
107
import allure
108

109
@allure.suite("Authentication Tests")         # Test suite grouping
110
@allure.parent_suite("User Management")       # Parent suite grouping  
111
@allure.sub_suite("Login Functionality")      # Sub-suite grouping
112
def test_login_validation():
113
    pass
114
```
115

116
## Usage Examples
117

118
### Basic Metadata Assignment
119

120
```python
121
import pytest
122
import allure
123

124
@pytest.mark.allure_label("critical", label_type="severity")
125
@pytest.mark.allure_label("authentication", label_type="feature")
126
@pytest.mark.allure_label("TC001", label_type="testId")
127
@pytest.mark.allure_link("PROJ-123", link_type="issue", name="Login Bug")
128
@pytest.mark.allure_description("Verify user can login with valid credentials")
129
def test_valid_login():
130
    """Test successful user authentication"""
131
    pass
132
```
133

134
### Comprehensive Test Documentation
135

136
```python
137
import pytest
138
import allure
139

140
@allure.severity(allure.severity_level.CRITICAL)
141
@allure.epic("User Management")
142
@allure.feature("Authentication")
143
@allure.story("User can login with valid credentials")
144
@allure.testcase("TC001", "Test Management System")
145
@allure.issue("PROJ-123", "Bug Tracker")
146
@pytest.mark.allure_description_html("""
147
<h3>Test Objective</h3>
148
<p>Verify that users can successfully authenticate with valid credentials</p>
149
<h3>Prerequisites</h3>
150
<ul>
151
    <li>User account exists</li>
152
    <li>Application is accessible</li>
153
</ul>
154
""")
155
def test_user_authentication():
156
    pass
157
```
158

159
### Custom Label Categories
160

161
```python
162
import pytest
163

164
@pytest.mark.allure_label("backend", label_type="component")
165
@pytest.mark.allure_label("database", label_type="layer") 
166
@pytest.mark.allure_label("regression", label_type="test_type")
167
@pytest.mark.allure_label("P1", label_type="priority")
168
@pytest.mark.allure_label("team_alpha", label_type="owner")
169
def test_database_connection():
170
    pass
171
```
172

173
### Multiple Links and References
174

175
```python
176
import pytest
177

178
@pytest.mark.allure_link("PROJ-123", link_type="issue", name="Original Bug")
179
@pytest.mark.allure_link("PROJ-456", link_type="issue", name="Related Issue")  
180
@pytest.mark.allure_link("TC001", link_type="tms", name="Test Case")
181
@pytest.mark.allure_link("https://wiki.company.com/auth", link_type="test_case", name="Documentation")
182
def test_authentication_flow():
183
    pass
184
```
185

186
## Marker Constants
187

188
The plugin defines these marker names as constants:
189

190
```python { .api }
191
ALLURE_LABEL_MARK = "allure_label"              # For @pytest.mark.allure_label
192
ALLURE_LINK_MARK = "allure_link"                # For @pytest.mark.allure_link  
193
ALLURE_DESCRIPTION_MARK = "allure_description"  # For @pytest.mark.allure_description
194
ALLURE_DESCRIPTION_HTML_MARK = "allure_description_html"  # For @pytest.mark.allure_description_html
195
```
196

197
## Integration with Test Filtering
198

199
Labels added through markers can be used with command-line filtering options:
200

201
```bash
202
# Run tests with specific labels
203
pytest --allure-severities critical tests/
204
pytest --allure-features authentication tests/
205
pytest --allure-label component=backend tests/
206
```