pytest-html

4.2.0 · active · verified Wed Apr 01

pytest-html is a plugin for the pytest testing framework that generates comprehensive HTML reports for test results. It provides a visual overview of test runs, including pass/fail status, durations, and detailed information for each test. The library is actively maintained, with version 4.2.0 being the current release, and follows a frequent release cadence, addressing bug fixes and improvements regularly.

Warnings

breaking Python 3.7 support was dropped in `pytest-html` v4.0.0. Ensure your Python environment is 3.8+ to use versions 4.x.x.
Fix: Upgrade Python to 3.8 or newer, or downgrade pytest-html to a 3.x.x version.
breaking The `py` module was removed as a dependency in `pytest-html` v4.0.0. If your `conftest.py` or custom plugins directly imported `py` for XML/HTML generation (e.g., `from py.xml import html`), you may need to adjust your code. While `py.xml.html` is still commonly used in examples, its direct dependency on `py` is gone.
Fix: Remove explicit dependencies on `py` if no longer needed. The `py.xml.html` module is still implicitly available via `pytest-html`'s internal usage or if `pytest` itself provides it, but consider direct HTML string generation for custom content where possible to reduce implicit dependencies.
deprecated Configuration options `duration_formatter` and `render_collapsed = True` were deprecated in v4.0.0. `duration_formatter` has no effect, and `render_collapsed = True` should be replaced with `render_collapsed = all` for consistency with query parameters.
Fix: Remove `duration_formatter` as it's no longer supported. Update `render_collapsed = True` in your `pytest.ini` or `pyproject.toml` to `render_collapsed = all`.
deprecated The `report.extra` attribute and the `extra` fixture were deprecated in v4.0.0. Use `report.extras` and the `extras` fixture instead for adding custom content to reports.
Fix: Update your `conftest.py` hooks or test functions to use `report.extras.append(...)` and inject content via the `extras` fixture instead of `extra`.
gotcha When using `--self-contained-html`, images or links added as external resources (e.g., screenshots saved to separate files) may not display correctly as they are not embedded into the report. The plugin will issue a warning.
Fix: For truly self-contained reports with images, embed images directly into the HTML using base64 encoding if possible, or ensure external image files are bundled and accessible alongside the report.
gotcha Customizing the report table using hooks like `pytest_html_results_table_header` might lead to empty result tables when running tests with tags in `pytest-html` v4.1.1 and v4.2.0 due to the hook not being invoked.
Fix: This is a known issue (GitHub #849). Check the project's issue tracker for updates. Downgrading to v3.2.0 might temporarily resolve it, or refactor custom column additions to a different hook or mechanism if available.

Install

pip install pytest-html Install stable version

Imports

pytest_html
```
import pytest_html
from py.xml import html # For HTML content in hooks
```
pytest-html is primarily used via command-line options or pytest.ini. Direct imports are typically for customizing reports using pytest hooks in 'conftest.py' files, for instance, to add custom content or modify report sections. The `py.xml.html` module is often imported when generating HTML content within these hooks.

Quickstart

Create a test file (e.g., `test_example.py`). Run pytest from your terminal, specifying the `--html` option to define the report filename and `--self-contained-html` to embed all CSS/JS directly into the HTML, making it easier to share.

import pytest

# test_example.py
def test_pass():
    assert True

def test_fail():
    assert False

def test_skipped():
    pytest.skip("This test is skipped")

# To run tests and generate a self-contained HTML report:
# $ pytest --html=report.html --self-contained-html
# (Run this command in your terminal where test_example.py is located)

view raw JSON →