0
# Formatter Integration
1

2
The AllureFormatter class provides the primary integration method for Allure Behave, implementing Behave's formatter interface to capture test execution events and generate Allure reports.
3

4
## Capabilities
5

6
### AllureFormatter Class
7

8
Main formatter class that extends Behave's base formatter to capture test execution events and generate comprehensive Allure reports.
9

10
```python { .api }
11
class AllureFormatter:
12
    def __init__(self, stream_opener, config):
13
        """
14
        Initialize the Allure formatter.
15
        
16
        Parameters:
17
        - stream_opener: Behave's stream opener for output handling
18
        - config: Behave configuration object containing test settings
19
        """
20
    
21
    def uri(self, uri):
22
        """
23
        Process feature file URI when starting a new feature file.
24
        
25
        Parameters:
26
        - uri (str): Path to the feature file being processed
27
        """
28
    
29
    def feature(self, feature):
30
        """
31
        Process feature object and wrap scenarios for Allure integration.
32
        
33
        Parameters:
34
        - feature: Behave feature object containing scenarios and metadata
35
        """
36
    
37
    def step(self, step):
38
        """
39
        Schedule a step for execution tracking.
40
        
41
        Parameters:
42
        - step: Behave step object with keyword, name, and optional table/text
43
        """
44
    
45
    def match(self, match):
46
        """
47
        Process step match with step definition.
48
        
49
        Parameters:
50
        - match: Behave match object linking step to its implementation
51
        """
52
    
53
    def result(self, result):
54
        """
55
        Process step execution result.
56
        
57
        Parameters:
58
        - result: Behave result object with status, duration, and exception info
59
        """
60
    
61
    def eof(self):
62
        """
63
        Handle end of feature file processing.
64
        """
65
    
66
    def close(self):
67
        """
68
        Clean up formatter resources and unregister plugins.
69
        """
70
    
71
    def close_stream(self):
72
        """
73
        Stop the test session and finalize reporting.
74
        """
75
```
76

77
## Usage Examples
78

79
### Command Line Usage
80

81
The most common way to use the AllureFormatter is via behave command line:
82

83
```bash
84
# Basic usage - generate reports in 'allure_results' directory
85
behave -f allure_behave.formatter:AllureFormatter -o allure_results ./features
86

87
# With specific output directory
88
behave -f allure_behave.formatter:AllureFormatter -o /path/to/results ./features
89

90
# Combined with other formatters (e.g., pretty for console output)
91
behave -f pretty -f allure_behave.formatter:AllureFormatter -o allure_results ./features
92

93
# With behave configuration options
94
behave -f allure_behave.formatter:AllureFormatter -o results \
95
       -D AllureFormatter.issue_pattern=https://jira.example.com/browse/{} \
96
       -D AllureFormatter.link_pattern=https://docs.example.com/{} \
97
       ./features
98
```
99

100
### Generating and Viewing Reports
101

102
After test execution, use Allure CLI to generate and serve reports:
103

104
```bash
105
# Generate static HTML report
106
allure generate allure_results -o allure_report --clean
107

108
# Serve report on local web server
109
allure serve allure_results
110

111
# Open generated report
112
allure open allure_report
113
```
114

115
### Configuration Options
116

117
Configure the formatter behavior using behave's userdata mechanism:
118

119
```bash
120
# Issue link pattern - converts @issue.ABC-123 tags to clickable links
121
behave -f allure_behave.formatter:AllureFormatter -o results \
122
       -D AllureFormatter.issue_pattern=https://jira.company.com/browse/{}
123

124
# Custom link pattern - converts @link.DOC-456 tags to documentation links  
125
behave -f allure_behave.formatter:AllureFormatter -o results \
126
       -D AllureFormatter.link_pattern=https://docs.company.com/{}
127

128
# Hide tests excluded by test plan
129
behave -f allure_behave.formatter:AllureFormatter -o results \
130
       -D AllureFormatter.hide_excluded=true
131
```
132

133
### Integration with CI/CD
134

135
Example Jenkins pipeline integration:
136

137
```groovy
138
pipeline {
139
    agent any
140
    stages {
141
        stage('Test') {
142
            steps {
143
                sh 'behave -f allure_behave.formatter:AllureFormatter -o allure_results ./features'
144
            }
145
            post {
146
                always {
147
                    allure includeProperties: false, 
148
                           jdk: '', 
149
                           results: [[path: 'allure_results']]
150
                }
151
            }
152
        }
153
    }
154
}
155
```
156

157
## Limitations
158

159
- **Parallel Execution**: The formatter approach doesn't work with behave-parallel. Use [Hooks Integration](./hooks.md) instead.
160
- **Custom Environment**: If you need custom before/after hooks that interact with Allure, use the hooks approach.
161
- **Multiple Processes**: Each process needs its own output directory to avoid conflicts.