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
```