0
# Report Customization Hooks
1
2
Pytest hooks that enable customization of HTML report content, formatting, and behavior. These hooks integrate with pytest's plugin system to provide extensive control over report generation and appearance.
3
4
## Capabilities
5
6
### Report Title Customization
7
8
Customizes the title displayed in the HTML report.
9
10
```python { .api }
11
def pytest_html_report_title(report):
12
"""
13
Called before adding the title to the report.
14
15
This hook allows modification of the report title that appears
16
at the top of the HTML report.
17
18
Parameters:
19
- report: Report object with title attribute that can be modified
20
21
Usage:
22
def pytest_html_report_title(report):
23
report.title = "Custom Test Report - " + report.title
24
"""
25
```
26
27
**Usage Example:**
28
29
```python
30
# In conftest.py
31
def pytest_html_report_title(report):
32
report.title = f"Test Results - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
33
```
34
35
### Results Summary Customization
36
37
Customizes the summary section that appears before the test results table.
38
39
```python { .api }
40
def pytest_html_results_summary(prefix, summary, postfix, session):
41
"""
42
Called before adding the summary section to the report.
43
44
This hook allows modification of the summary information displayed
45
above the test results table, including test counts and duration.
46
47
Parameters:
48
- prefix (list): List of summary items to display before main summary
49
- summary (list): List of main summary items (test counts, duration)
50
- postfix (list): List of summary items to display after main summary
51
- session: pytest session object
52
53
Usage:
54
def pytest_html_results_summary(prefix, summary, postfix, session):
55
prefix.append("Custom prefix information")
56
postfix.append("Custom postfix information")
57
"""
58
```
59
60
**Usage Example:**
61
62
```python
63
# In conftest.py
64
def pytest_html_results_summary(prefix, summary, postfix, session):
65
# Add environment information
66
prefix.append(f"Test Environment: {os.environ.get('TEST_ENV', 'unknown')}")
67
68
# Add custom metrics
69
postfix.append(f"Total Test Files: {len(session.items)}")
70
```
71
72
### Table Header Customization
73
74
Customizes the column headers in the test results table.
75
76
```python { .api }
77
def pytest_html_results_table_header(cells):
78
"""
79
Called after building results table header.
80
81
This hook allows modification of the table header columns,
82
including adding custom columns or reordering existing ones.
83
84
Parameters:
85
- cells (list): List of HTML strings representing table header cells
86
87
Usage:
88
def pytest_html_results_table_header(cells):
89
cells.insert(1, '<th class="sortable">Priority</th>')
90
"""
91
```
92
93
**Usage Example:**
94
95
```python
96
# In conftest.py
97
def pytest_html_results_table_header(cells):
98
# Add a column for test category
99
cells.insert(1, '<th class="sortable" data-column-type="category">Category</th>')
100
101
# Add a column for custom metadata
102
cells.append('<th>Custom Info</th>')
103
```
104
105
### Table Row Customization
106
107
Customizes individual rows in the test results table.
108
109
```python { .api }
110
def pytest_html_results_table_row(report, cells):
111
"""
112
Called after building results table row.
113
114
This hook allows modification of individual test result rows,
115
including adding custom cell content that corresponds to custom headers.
116
117
Parameters:
118
- report: pytest test report object
119
- cells (list): List of HTML strings representing table row cells
120
121
Usage:
122
def pytest_html_results_table_row(report, cells):
123
# Add custom cell content
124
priority = getattr(report, 'priority', 'normal')
125
cells.insert(1, f'<td>{priority}</td>')
126
"""
127
```
128
129
**Usage Example:**
130
131
```python
132
# In conftest.py
133
def pytest_html_results_table_row(report, cells):
134
# Add test category based on node ID
135
if 'unit' in report.nodeid:
136
category = 'Unit'
137
elif 'integration' in report.nodeid:
138
category = 'Integration'
139
else:
140
category = 'Other'
141
142
cells.insert(1, f'<td>{category}</td>')
143
144
# Add custom metadata
145
custom_info = getattr(report, 'custom_data', 'N/A')
146
cells.append(f'<td>{custom_info}</td>')
147
```
148
149
### Additional HTML Content
150
151
Adds custom HTML content to individual test results.
152
153
```python { .api }
154
def pytest_html_results_table_html(report, data):
155
"""
156
Called after building results table additional HTML.
157
158
This hook allows addition of custom HTML content that appears
159
in the expandable section of each test result row.
160
161
Parameters:
162
- report: pytest test report object
163
- data (list): List of HTML strings for additional content
164
165
Usage:
166
def pytest_html_results_table_html(report, data):
167
if hasattr(report, 'custom_html'):
168
data.append(report.custom_html)
169
"""
170
```
171
172
**Usage Example:**
173
174
```python
175
# In conftest.py
176
def pytest_html_results_table_html(report, data):
177
# Add custom debugging information
178
if hasattr(report, 'debug_info'):
179
debug_html = f"""
180
<div class="debug-info">
181
<h3>Debug Information</h3>
182
<pre>{report.debug_info}</pre>
183
</div>
184
"""
185
data.append(debug_html)
186
```
187
188
### Duration Formatting
189
190
Customizes how test durations are formatted and displayed.
191
192
```python { .api }
193
def pytest_html_duration_format(duration):
194
"""
195
Called before using the default duration formatting.
196
197
This hook allows customization of how test execution durations
198
are formatted in the HTML report.
199
200
Parameters:
201
- duration (float): Test duration in seconds
202
203
Returns:
204
- str or None: Custom formatted duration string, or None to use default
205
206
Usage:
207
def pytest_html_duration_format(duration):
208
if duration < 1:
209
return f"{duration*1000:.0f}ms"
210
return f"{duration:.2f}s"
211
"""
212
```
213
214
**Usage Example:**
215
216
```python
217
# In conftest.py
218
def pytest_html_duration_format(duration):
219
# Format durations with appropriate units
220
if duration < 0.001:
221
return f"{duration*1000000:.0f}μs"
222
elif duration < 1:
223
return f"{duration*1000:.0f}ms"
224
elif duration < 60:
225
return f"{duration:.2f}s"
226
else:
227
minutes = int(duration // 60)
228
seconds = duration % 60
229
return f"{minutes}m {seconds:.1f}s"
230
```
231
232
## Hook Implementation
233
234
All hooks are implemented using pytest's hookimpl decorator and can be defined in `conftest.py` files or pytest plugins:
235
236
```python
237
import pytest
238
239
@pytest.hookimpl
240
def pytest_html_report_title(report):
241
# Implementation here
242
pass
243
244
# Or without decorator for simple hooks
245
def pytest_html_results_summary(prefix, summary, postfix, session):
246
# Implementation here
247
pass
248
```
249
250
## Integration with Report Generation
251
252
These hooks are called at specific points during HTML report generation:
253
254
1. **pytest_html_report_title**: Called when setting up the report structure
255
2. **pytest_html_results_summary**: Called before rendering the summary section
256
3. **pytest_html_results_table_header**: Called when building the table header
257
4. **pytest_html_results_table_row**: Called for each test result row
258
5. **pytest_html_results_table_html**: Called when adding extra HTML content
259
6. **pytest_html_duration_format**: Called when formatting duration values
260
261
The hooks provide a powerful way to customize reports without modifying the core plugin code, enabling teams to adapt the HTML reports to their specific needs and branding requirements.