0
# Hooks Integration
1

2
The hooks integration provides an alternative method for integrating Allure Behave that works with parallel execution and custom environment setups. It automatically wraps your existing behave hooks to add Allure reporting capabilities.
3

4
## Capabilities
5

6
### allure_report Function
7

8
Main public API function that sets up Allure reporting via behave hooks. Call this function at the module level in your `environment.py` file.
9

10
```python { .api }
11
def allure_report(result_dir="allure_results"):
12
    """
13
    Set up Allure reporting using behave hooks integration.
14
    
15
    This function automatically wraps existing behave hooks in the calling scope
16
    and adds new hooks if they don't exist. Must be called at module level.
17
    
18
    Parameters:
19
    - result_dir (str): Directory where Allure results will be written.
20
                       Defaults to "allure_results"
21
    
22
    Returns:
23
    None
24
    
25
    Side Effects:
26
    - Modifies hook functions in the calling frame's locals
27
    - Registers Allure plugins with allure_commons
28
    - Creates result directory if it doesn't exist
29
    """
30
```
31

32
### AllureHooks Class
33

34
Internal class that implements the actual behave hook methods for Allure integration. This class is used internally by `allure_report()` and typically doesn't need to be used directly.
35

36
```python { .api }
37
class AllureHooks:
38
    def __init__(self, result_dir):
39
        """
40
        Initialize Allure hooks integration.
41
        
42
        Parameters:
43
        - result_dir (str): Directory for Allure result files
44
        """
45
    
46
    def after_all(self, context):
47
        """
48
        Clean up Allure plugins after all tests complete.
49
        
50
        Parameters:
51
        - context: Behave context object
52
        """
53
    
54
    def before_feature(self, context, feature):
55
        """
56
        Start processing a new feature file.
57
        
58
        Parameters:
59
        - context: Behave context object
60
        - feature: Behave feature object
61
        """
62
    
63
    def after_feature(self, context, feature):
64
        """
65
        Complete processing of a feature file.
66
        
67
        Parameters:
68
        - context: Behave context object  
69
        - feature: Behave feature object
70
        """
71
    
72
    def before_scenario(self, context, scenario):
73
        """
74
        Start processing a scenario.
75
        
76
        Parameters:
77
        - context: Behave context object
78
        - scenario: Behave scenario object
79
        """
80
    
81
    def after_scenario(self, context, scenario):
82
        """
83
        Complete processing of a scenario.
84
        
85
        Parameters:
86
        - context: Behave context object
87
        - scenario: Behave scenario object
88
        """
89
    
90
    def before_step(self, context, step):
91
        """
92
        Start processing a step.
93
        
94
        Parameters:
95
        - context: Behave context object
96
        - step: Behave step object
97
        """
98
    
99
    def after_step(self, context, step):
100
        """
101
        Complete processing of a step.
102
        
103
        Parameters:
104
        - context: Behave context object
105
        - step: Behave step object with execution result
106
        """
107
```
108

109
## Usage Examples
110

111
### Basic Environment Setup
112

113
Create or modify your `environment.py` file:
114

115
```python
116
# environment.py
117
from allure_behave.hooks import allure_report
118

119
# Set up Allure reporting - call this at module level
120
allure_report("allure_results")
121

122
# Your existing hooks will be automatically wrapped
123
def before_all(context):
124
    # Your setup code
125
    print("Setting up test environment")
126

127
def after_all(context):
128
    # Your cleanup code  
129
    print("Cleaning up test environment")
130

131
def before_feature(context, feature):
132
    # Your feature setup
133
    context.feature_data = {}
134

135
def after_feature(context, feature):
136
    # Your feature cleanup
137
    del context.feature_data
138
```
139

140
### Custom Result Directory
141

142
```python  
143
# environment.py
144
from allure_behave.hooks import allure_report
145

146
# Custom result directory
147
allure_report("/path/to/custom/results")
148

149
# Rest of your environment setup...
150
```
151

152
### Parallel Execution Setup
153

154
For use with behave-parallel or similar tools:
155

156
```python
157
# environment.py  
158
from allure_behave.hooks import allure_report
159
import os
160

161
# Use unique directory per process for parallel execution
162
process_id = os.getpid()
163
allure_report(f"allure_results_{process_id}")
164

165
def before_all(context):
166
    # Process-specific setup
167
    context.process_id = process_id
168
```
169

170
### Integration with Existing Hooks
171

172
The hooks integration automatically wraps your existing hooks:
173

174
```python
175
# environment.py
176
from allure_behave.hooks import allure_report
177

178
# Set up Allure first
179
allure_report("results")
180

181
# Your existing hooks are automatically wrapped
182
def before_scenario(context, scenario):
183
    # Your code runs first
184
    setup_scenario_data(context, scenario)
185
    # Then Allure processing happens automatically
186

187
def after_scenario(context, scenario):
188
    # Your code runs first  
189
    cleanup_scenario_data(context, scenario)
190
    # Then Allure processing happens automatically
191
```
192

193
### Conditional Allure Integration
194

195
Enable Allure reporting conditionally:
196

197
```python
198
# environment.py
199
import os
200
from allure_behave.hooks import allure_report
201

202
# Only enable Allure in CI or when explicitly requested
203
if os.getenv('CI') or os.getenv('ALLURE_RESULTS_DIR'):
204
    result_dir = os.getenv('ALLURE_RESULTS_DIR', 'allure_results')
205
    allure_report(result_dir)
206

207
def before_all(context):
208
    context.allure_enabled = bool(os.getenv('CI') or os.getenv('ALLURE_RESULTS_DIR'))
209
```
210

211
## Hook Wrapping Behavior
212

213
The `allure_report()` function automatically handles hook wrapping:
214

215
1. **Existing Hooks**: If you already have hook functions defined, they are wrapped to run your code first, then Allure processing
216
2. **Missing Hooks**: If you don't have certain hooks defined, they are created automatically
217
3. **Multiple Calls**: Calling `allure_report()` multiple times in the same module is safe - it won't create duplicate wrappers
218

219
## Thread Safety
220

221
The hooks integration uses thread-local storage for shared state, making it safe for parallel execution scenarios where multiple processes or threads are running tests simultaneously.
222

223
## Comparison with Formatter Integration
224

225
| Feature | Hooks Integration | Formatter Integration |
226
|---------|------------------|----------------------|
227
| Parallel Execution | ✅ Supported | ❌ Not supported |
228
| Custom Environment | ✅ Full control | ⚠️ Limited |  
229
| Setup Complexity | Medium | Low |
230
| CLI Integration | Requires environment.py | Direct |
231
| Performance | Slightly slower | Faster |