0
# pytest-html
1
2
A comprehensive pytest plugin that generates professional HTML reports for test results. pytest-html captures test execution data, metadata, and results, then renders them into visually appealing and interactive HTML reports with filtering capabilities, detailed test information, and support for embedded multimedia content.
3
4
## Package Information
5
6
- **Package Name**: pytest-html
7
- **Language**: Python
8
- **Installation**: `pip install pytest-html`
9
10
## Core Imports
11
12
```python
13
import pytest_html
14
```
15
16
For accessing extras functionality:
17
18
```python
19
import pytest_html.extras
20
```
21
22
For accessing specific extras functions:
23
24
```python
25
from pytest_html import extras
26
from pytest_html.extras import html, image, json, text, url, video
27
```
28
29
## Basic Usage
30
31
```python
32
# Generate a basic HTML report
33
# Command line: pytest --html=report.html
34
35
# Add extra information to a test
36
def test_example(extras):
37
extras.append(pytest_html.extras.url("https://example.com"))
38
extras.append(pytest_html.extras.text("Additional context"))
39
assert True
40
41
# Generate self-contained report (embeds CSS/JS)
42
# Command line: pytest --html=report.html --self-contained-html
43
```
44
45
## Architecture
46
47
pytest-html integrates with pytest's plugin system and hook architecture:
48
49
- **Plugin Entry Points**: Registered as pytest11 plugins for automatic discovery
50
- **Report Generation**: Uses Jinja2 templating for flexible HTML generation
51
- **Asset Management**: Supports both linked assets and self-contained reports
52
- **Extensibility**: Provides hooks for customizing report content and formatting
53
- **Test Integration**: Uses pytest fixtures to collect additional test metadata
54
55
## Capabilities
56
57
### Command Line Interface
58
59
Core command-line options and configuration settings for controlling HTML report generation, output format, and styling options.
60
61
```bash { .api }
62
# Command line options
63
--html=PATH # Create HTML report file at given path
64
--self-contained-html # Create self-contained HTML with embedded assets
65
--css=PATH # Append CSS file content to report style (can be used multiple times)
66
```
67
68
```ini { .api }
69
# Configuration options (pytest.ini)
70
[tool:pytest]
71
render_collapsed = "passed" # Row(s) to render collapsed on open
72
max_asset_filename_length = 255 # Maximum filename length for assets
73
initial_sort = "result" # Column to initially sort on
74
generate_report_on_test = false # Generate report after each test
75
environment_table_redact_list = # Regexes for redacting env variables
76
password.*
77
secret.*
78
```
79
80
### Test Fixtures
81
82
Fixtures for adding multimedia content, metadata, and additional information to individual test results within the HTML report.
83
84
```python { .api }
85
@pytest.fixture
86
def extras(pytestconfig): ...
87
88
@pytest.fixture
89
def extra(pytestconfig): ... # DEPRECATED: Use extras instead
90
```
91
92
[Test Fixtures](./fixtures.md)
93
94
### Content Extras
95
96
Functions for creating rich multimedia content that can be embedded in HTML test reports, including images, videos, JSON data, and external links.
97
98
```python { .api }
99
def html(content): ...
100
def image(content, name="Image", mime_type="image/png", extension="png"): ...
101
def json(content, name="JSON"): ...
102
def text(content, name="Text"): ...
103
def url(content, name="URL"): ...
104
def video(content, name="Video", mime_type="video/mp4", extension="mp4"): ...
105
```
106
107
[Content Extras](./extras.md)
108
109
### Report Customization Hooks
110
111
Pytest hooks for customizing report content, formatting, and behavior during report generation.
112
113
```python { .api }
114
def pytest_html_report_title(report): ...
115
def pytest_html_results_summary(prefix, summary, postfix, session): ...
116
def pytest_html_results_table_header(cells): ...
117
def pytest_html_results_table_row(report, cells): ...
118
def pytest_html_results_table_html(report, data): ...
119
def pytest_html_duration_format(duration): ...
120
```
121
122
[Report Customization Hooks](./hooks.md)
123
124
## Types
125
126
```python { .api }
127
# Extra content structure (dictionary returned by extra functions)
128
Extra = {
129
"name": str | None,
130
"format_type": str,
131
"content": str,
132
"mime_type": str | None,
133
"extension": str | None
134
}
135
136
# Format type constants
137
FORMAT_HTML = "html"
138
FORMAT_IMAGE = "image"
139
FORMAT_JSON = "json"
140
FORMAT_TEXT = "text"
141
FORMAT_URL = "url"
142
FORMAT_VIDEO = "video"
143
144
# Package metadata
145
__version__ = "4.1.1" # Or "unknown" if package is not built with setuptools_scm
146
__pypi_url__ = "https://pypi.python.org/pypi/pytest-html"
147
```