0
# allure-python-commons
1
2
A comprehensive Python library providing the core API and infrastructure for creating Allure test adapters. It offers a complete object model for Allure Report generation, lifecycle management for test execution tracking, and both file-based and memory-based logging implementations for emitting test results, containers, and attachments. Designed for maximum reusability across Python testing frameworks.
3
4
## Package Information
5
6
- **Package Name**: allure-python-commons
7
- **Type**: Python Library
8
- **Language**: Python
9
- **Installation**: `pip install allure-python-commons`
10
11
## Core Imports
12
13
```python
14
import allure
15
```
16
17
For adapter development:
18
19
```python
20
import allure_commons
21
```
22
23
## Basic Usage
24
25
```python
26
import allure
27
28
# Basic test enhancement with decorators
29
@allure.title("Test user authentication")
30
@allure.description("Verify that users can authenticate with valid credentials")
31
@allure.severity(allure.severity_level.CRITICAL)
32
@allure.feature("Authentication")
33
@allure.story("User Login")
34
def test_user_login():
35
# Test implementation
36
with allure.step("Enter username"):
37
enter_username("testuser")
38
39
with allure.step("Enter password"):
40
enter_password("secret123")
41
42
with allure.step("Click login button"):
43
click_login()
44
45
# Attach screenshot on failure
46
allure.attach(
47
screenshot_bytes,
48
name="Login failure screenshot",
49
attachment_type=allure.attachment_type.PNG
50
)
51
52
# Dynamic test modification at runtime
53
def test_dynamic_enhancement():
54
allure.dynamic.title("Dynamic test title")
55
allure.dynamic.description("Added description at runtime")
56
allure.dynamic.label("owner", "test-team")
57
allure.dynamic.link("https://issues.example.com/BUG-123", "Bug Report")
58
```
59
60
## Architecture
61
62
The allure-python-commons library is built on a plugin-based architecture that provides maximum flexibility and extensibility:
63
64
- **Plugin System**: Hook-based architecture using pluggy for extensible test reporting
65
- **Lifecycle Management**: Context managers and lifecycle classes for managing test execution phases
66
- **Data Model**: Comprehensive data structures representing test results, containers, fixtures, and attachments
67
- **Reporter System**: Multiple reporters (file-based, memory-based) for different output needs
68
- **Thread Safety**: Thread-aware context management for parallel test execution
69
70
This design enables the library to serve as the foundation for multiple Python testing framework adapters (pytest, behave, nose2, robotframework) while maintaining consistency in Allure report generation.
71
72
## Capabilities
73
74
### Test Decorators
75
76
Comprehensive set of decorators for enhancing test metadata including titles, descriptions, labels, severities, links, and organizational markers like epics, features, and stories.
77
78
```python { .api }
79
def title(test_title): ...
80
def description(test_description): ...
81
def severity(severity_level): ...
82
def feature(*features): ...
83
def story(*stories): ...
84
def epic(*epics): ...
85
def tag(*tags): ...
86
def manual(fn): ...
87
def link(url, link_type=LinkType.LINK, name=None): ...
88
def issue(url, name=None): ...
89
def testcase(url, name=None): ...
90
91
class Dynamic:
92
@staticmethod
93
def parameter(name, value, excluded=None, mode=None): ...
94
```
95
96
[Test Decorators](./test-decorators.md)
97
98
### Test Lifecycle Management
99
100
Context managers and classes for managing test execution phases, including test cases, fixtures, steps, and containers with proper lifecycle tracking.
101
102
```python { .api }
103
def step(title): ...
104
def attach(body, name=None, attachment_type=None, extension=None): ...
105
106
class Attach:
107
@staticmethod
108
def file(source, name=None, attachment_type=None, extension=None): ...
109
110
class AllureLifecycle:
111
def schedule_test_case(self, uuid=None): ...
112
def start_step(self, parent_uuid=None, uuid=None): ...
113
def start_container(self, uuid=None): ...
114
def start_before_fixture(self, parent_uuid=None, uuid=None): ...
115
def start_after_fixture(self, parent_uuid=None, uuid=None): ...
116
```
117
118
[Test Lifecycle](./test-lifecycle.md)
119
120
### Data Models
121
122
Complete set of data structures for representing Allure test results, containers, attachments, and metadata with proper serialization support.
123
124
```python { .api }
125
class TestResult(ExecutableItem):
126
uuid: str
127
labels: List[Label]
128
links: List[Link]
129
status: str
130
131
class TestResultContainer:
132
uuid: str
133
befores: List[TestBeforeResult]
134
afters: List[TestAfterResult]
135
```
136
137
[Data Models](./data-models.md)
138
139
### Plugin System
140
141
Hook-based plugin architecture enabling extensible test reporting with separate hooks for end users and adapter developers.
142
143
```python { .api }
144
@hookspec
145
def decorate_as_title(test_title): ...
146
147
@hookspec
148
def start_test(parent_uuid, uuid, name, parameters, context): ...
149
150
plugin_manager = PluginManager('allure')
151
```
152
153
[Plugin System](./plugin-system.md)
154
155
### Utilities
156
157
Helper functions for UUID generation, timestamp management, parameter extraction, string formatting, and platform detection.
158
159
```python { .api }
160
def uuid4() -> str: ...
161
def now() -> int: ...
162
def func_parameters(func, *args, **kwargs) -> OrderedDict: ...
163
def represent(item) -> str: ...
164
```
165
166
[Utilities](./utilities.md)
167
168
## Types and Enums
169
170
```python { .api }
171
class Severity:
172
BLOCKER = 'blocker'
173
CRITICAL = 'critical'
174
NORMAL = 'normal'
175
MINOR = 'minor'
176
TRIVIAL = 'trivial'
177
178
class ParameterMode:
179
HIDDEN = 'hidden'
180
MASKED = 'masked'
181
DEFAULT = None
182
183
class AttachmentType:
184
# Text formats
185
TEXT = 'text/plain'
186
JSON = 'application/json'
187
XML = 'application/xml'
188
HTML = 'text/html'
189
CSV = 'text/csv'
190
191
# Image formats
192
PNG = 'image/png'
193
JPG = 'image/jpeg'
194
SVG = 'image/svg+xml'
195
196
# Video formats
197
MP4 = 'video/mp4'
198
WEBM = 'video/webm'
199
200
# Document formats
201
PDF = 'application/pdf'
202
```