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`