0
# Allure Pytest
1

2
A pytest plugin that integrates with the Allure reporting framework to generate comprehensive test reports. The plugin enables pytest tests to produce detailed test execution reports with rich attachments, steps, metadata, and visual test results that can be viewed through Allure's web-based reporting interface.
3

4
## Package Information
5

6
- **Package Name**: allure-pytest
7
- **Language**: Python
8
- **Installation**: `pip install allure-pytest`
9
- **Package Type**: pytest plugin
10

11
## Core Imports
12

13
The plugin automatically integrates with pytest when installed. Use the main allure module for decorators and dynamic API:
14

15
```python
16
import allure
17
```
18

19
For pytest markers:
20

21
```python
22
import pytest
23
```
24

25
## Basic Usage
26

27
```python
28
import allure
29
import pytest
30

31
# Basic test with Allure decorators
32
@allure.title("User Authentication Test")
33
@allure.description("Verify user can log in with valid credentials")
34
@allure.severity(allure.severity_level.CRITICAL)
35
@allure.feature("Authentication")
36
@allure.story("User Login")
37
def test_user_login():
38
    with allure.step("Navigate to login page"):
39
        # Test implementation
40
        pass
41
    
42
    with allure.step("Enter credentials"):
43
        allure.dynamic.parameter("username", "test_user")
44
        # Test implementation
45
        pass
46
    
47
    with allure.step("Verify successful login"):
48
        # Test implementation
49
        pass
50

51
# Run tests with Allure reporting
52
# pytest --alluredir=./allure-results tests/
53
# allure serve ./allure-results
54
```
55

56
## Architecture
57

58
The allure-pytest plugin follows a hook-based architecture that integrates seamlessly with pytest's execution flow:
59

60
- **Plugin Entry Point**: Registered via `pytest11` entry point for automatic discovery
61
- **Command Line Integration**: Adds Allure-specific options to pytest CLI
62
- **Test Collection Filtering**: Supports filtering tests by labels, test plans, and metadata
63
- **Event Listeners**: Hooks into pytest test lifecycle events to collect reporting data
64
- **Report Generation**: Writes structured JSON test results for Allure report generation
65

66
## Capabilities
67

68
### Command Line Options
69

70
Control Allure reporting behavior through pytest command-line options including output directory configuration, test filtering by labels, and attachment settings.
71

72
```python { .api }
73
# Core options
74
--alluredir DIR                    # Generate Allure report in specified directory
75
--clean-alluredir                  # Clean alluredir folder if it exists
76
--allure-no-capture               # Do not attach pytest captured output
77
```
78

79
[Command Line Interface](./command-line.md)
80

81
### Test Filtering and Selection
82

83
Filter and select tests based on Allure labels, test plans, and metadata for targeted test execution and reporting.
84

85
```python { .api }
86
# Label-based filtering options
87
--allure-severities SEVERITIES_SET    # Filter by severity levels
88
--allure-features FEATURES_SET        # Filter by feature labels  
89
--allure-stories STORIES_SET          # Filter by story labels
90
--allure-epics EPICS_SET             # Filter by epic labels
91
--allure-ids IDS_SET                 # Filter by test ID labels
92
--allure-label LABEL_NAME=values     # Filter by custom labels
93
```
94

95
[Test Filtering](./test-filtering.md)
96

97
### Test Metadata and Labels
98

99
Add rich metadata to tests using pytest markers for categorization, organization, and enhanced reporting in the Allure interface.
100

101
```python { .api }
102
@pytest.mark.allure_label(label_type="feature", "User Management")
103
@pytest.mark.allure_label(label_type="story", "User Registration")  
104
@pytest.mark.allure_link(url="http://example.com/issue/123", link_type="issue", name="Bug-123")
105
```
106

107
[Test Metadata](./test-metadata.md)
108

109
### Allure Decorators and Static API
110

111
Decorate test functions with metadata using static decorators from the allure module for comprehensive test documentation.
112

113
```python { .api }
114
@allure.title(name: str)                                  # Set test title
115
@allure.description(description: str)                    # Set test description
116
@allure.description_html(html_description: str)          # Set HTML description
117
@allure.severity(severity_level: str)                    # Set test severity
118
@allure.epic(*epics: str)                               # Add epic labels
119
@allure.feature(*features: str)                         # Add feature labels
120
@allure.story(*stories: str)                            # Add story labels
121
@allure.suite(suite_name: str)                          # Set suite label
122
@allure.parent_suite(parent_suite_name: str)            # Set parent suite
123
@allure.sub_suite(sub_suite_name: str)                  # Set sub suite
124
@allure.tag(*tags: str)                                 # Add tags
125
@allure.id(test_id: str)                                # Set test ID
126
@allure.link(url: str, link_type: str, name: str)       # Add link
127
@allure.issue(url: str, name: str)                      # Add issue link
128
@allure.testcase(url: str, name: str)                   # Add test case link
129
@allure.manual                                          # Mark as manual test
130
```
131

132
### Steps and Attachments
133

134
Enhance test reporting with step-by-step execution tracking and rich attachments including files, screenshots, and data.
135

136
```python { .api }
137
@allure.step(title: str)                                        # Step decorator
138
allure.step(title: str)                                         # Step context manager
139
allure.attach(body: Any, name: str, attachment_type: str)       # Attach data
140
allure.attach.file(source: str, name: str, attachment_type: str) # Attach file
141
```
142

143
[Steps and Attachments](./steps-attachments.md)\n\n### Dynamic Test Enhancement
144

145
Dynamically modify test metadata, add parameters, and enhance test reporting during test execution using the allure module's dynamic API.
146

147
```python { .api }
148
# Key dynamic functions (from allure module)
149
allure.dynamic.title(name: str)                                    # Set test title
150
allure.dynamic.description(description: str)                      # Set test description  
151
allure.dynamic.description_html(html_description: str)            # Set HTML description
152
allure.dynamic.parameter(name: str, value: Any, excluded: bool, mode: str) # Add test parameter
153
allure.dynamic.label(label_type: str, label_value: str)           # Add test label
154
allure.dynamic.severity(severity_level: str)                      # Set test severity
155
allure.dynamic.epic(*epics: str)                                  # Add epic labels
156
allure.dynamic.feature(*features: str)                            # Add feature labels
157
allure.dynamic.story(*stories: str)                               # Add story labels
158
allure.dynamic.suite(suite_name: str)                             # Set suite label
159
allure.dynamic.parent_suite(parent_suite_name: str)               # Set parent suite
160
allure.dynamic.sub_suite(sub_suite_name: str)                     # Set sub suite
161
allure.dynamic.tag(*tags: str)                                    # Add tags
162
allure.dynamic.id(test_id: str)                                   # Set test ID
163
allure.dynamic.link(url: str, link_type: str, name: str)          # Add test link
164
allure.dynamic.issue(url: str, name: str)                         # Add issue link
165
allure.dynamic.testcase(url: str, name: str)                      # Add test case link
166
allure.dynamic.manual()                                           # Mark as manual test
167
```
168

169
This capability relies on the main `allure` module rather than the plugin directly.
170

171
## Types
172

173
### Label Types
174

175
```python { .api }
176
class LabelType:
177
    """Standard label types for test categorization."""
178
    SEVERITY = "severity"
179
    FEATURE = "feature" 
180
    STORY = "story"
181
    EPIC = "epic"
182
    ID = "as_id"
183
    SUITE = "suite"
184
    PARENT_SUITE = "parentSuite"
185
    SUB_SUITE = "subSuite"
186
    HOST = "host"
187
    THREAD = "thread"
188
    FRAMEWORK = "framework"
189
    LANGUAGE = "language"
190
    TAG = "tag"
191
```
192

193
### Severity Levels
194

195
```python { .api }
196
class Severity:
197
    """Test severity levels for prioritization.""" 
198
    BLOCKER = "blocker"
199
    CRITICAL = "critical"
200
    NORMAL = "normal"
201
    MINOR = "minor"
202
    TRIVIAL = "trivial"
203
```
204

205
### Attachment Types
206

207
```python { .api }
208
class AttachmentType:
209
    """Standard attachment types for test artifacts."""
210
    TEXT = "text/plain"
211
    CSV = "text/csv"
212
    TSV = "text/tab-separated-values"
213
    URI_LIST = "text/uri-list"
214
    HTML = "text/html"
215
    XML = "application/xml"
216
    JSON = "application/json"
217
    YAML = "application/yaml"
218
    PCAP = "application/vnd.tcpdump.pcap"
219
    PNG = "image/png"
220
    JPG = "image/jpg"
221
    SVG = "image/svg+xml"
222
    GIF = "image/gif"
223
    BMP = "image/bmp"
224
    TIFF = "image/tiff"
225
    MP4 = "video/mp4"
226
    OGG = "video/ogg"
227
    WEBM = "video/webm"
228
    PDF = "application/pdf"
229
```
230

231
### Parameter Modes
232

233
```python { .api }
234
class ParameterMode:
235
    """Parameter display modes for test parameters."""
236
    HIDDEN = "hidden"    # Parameter hidden from report
237
    MASKED = "masked"    # Parameter value masked in report
238
    DEFAULT = None       # Parameter shown normally
239
```
240

241
## Error Handling
242

243
The plugin handles various error conditions:
244

245
- **Configuration Errors**: Invalid command-line options or conflicting settings
246
- **Test Execution Errors**: Captures exceptions and maps them to appropriate Allure statuses
247
- **Report Generation Errors**: Issues with writing test results or attachments
248

249
Test status mapping:
250
- `AssertionError` or `pytest.fail.Exception` → `FAILED`
251
- `pytest.skip.Exception` → `SKIPPED` 
252
- Other exceptions → `BROKEN`
253
- No exceptions → `PASSED`