pytest-html is a plugin for pytest that generates a HTML report for the test results.

You will need the following prerequisites in order to use pytest-html:

• Python 2.7, 3.6, PyPy, or PyPy3

To install pytest-html:

$ pip install pytest-html

Then run your tests with:

$ pytest --html=report.html

Note that ANSI code support depends on the ansi2html package. Due to the use of a less permissive license, this package is not included as a dependency. If you have this package installed, then ANSI codes will be converted to HTML in your report.

In order to respect the Content Security Policy (CSP), several assets such as CSS and images are stored separately by default. You can alternatively create a self-contained report, which can be more convenient when sharing your results. This can be done in the following way:

$ pytest --html=report.html --self-contained-html

Images added as files or links are going to be linked as external resources, meaning that the standalone report HTML-file may not display these images as expected.

The plugin will issue a warning when adding files or links to the standalone report.

The output of the tests is grouped based on the effective branching logic of the tests and their fixtures, which is determined by the file structure of your project and how parameterized fixtures are defined/used. If using the pytest-xdist plugin to run tests in parallel, the workers are, by default, factored into this grouping logic, as this can have meaningful impact on how the tests operate. This can be turned off by using the --no-group-on-worker option.

When using parameterized fixtures with autouse, the plugin will determine what level is effectively being branched off for each permutation, based on the scope the fixture was defined in, and the scope is was meant to apply for. The level it's branching on will show as multiple copies of the same group, but each with a description of their respective instance of the parameterized fixture.

By default, everything is collapsed. As groups are expanded, their contents are generated at that moment. When they are collapsed, their contents are removed from the DOM.

Custom CSS (Cascasding Style Sheets) can be passed on the command line using the --css option. These will be applied in the order specified, and can be used to change the appearance of the report.

$ pytest --html=report.html --css=highcontrast.css --css=accessible.css

Custom JavaScript additions can be passed on the command line using the --js option. These will be applied in the order specified, and can be used to change the scripts of the report that are used to generate the structure of the test output, and define the behavior of interactive elements.

$ pytest --html=report.html --js=slideshow.js --css=structure.js

The Environment section is provided by the pytest-metadata, plugin, and can be accessed via the pytest_configure hook:

def pytest_configure(config):
    config._metadata['foo'] = 'bar'

The generated table will be sorted alphabetically unless the metadata is a collections.OrderedDict.

You can edit the Summary section by using the pytest_html_results_summary hook:

import pytest
from py.xml import html

@pytest.mark.optionalhook
def pytest_html_results_summary(summary):
    summary.extend([html.p("foo: bar")])

You can add details to the HTML reports by appending to the 'extra' list on one of the nodes in the pytest_html_add_node_chain_extra hook. The nodes represent the different levels of branching logic of your tests, and extra content can be added for each of them. The extra content added to the nodes is also persistent from test to test, so you can see what was added as the tests run. The item argument is also provided immediately following each test's execution, and can provide a gateway to accessing resources used by the test.

Here are the types of extra content that can be added:

Note: When adding an image from file, the path can be either absolute or relative.

Note: When using --self-contained-html, images added as files or links may not work as expected, see section Creating a self-contained report for more info.

There are also convenient types for several image formats:

The following example adds the various types of extras using a pytest_html_add_node_chain_extra hook, which can be implemented in a plugin or conftest.py file:

import pytest

def pytest_html_add_node_chain_extra(item, outcome, extra, node_chain):
    pytest_html = item.config.pluginmanager.getplugin('html')
    module_node = None
    for node in node_chain:
        if node.name.endswith(".py"):
            module_node = node
            break
    if module_node.extra:
        # already has extra
        return
    # always add url to report
    module_node.extra.append(pytest_html.extras.url('http://www.example.com/'))
    if outcome == 'Failed':
        # only add additional html on failure
        module_node.extra.append(pytest_html.extras.html('<div>Additional HTML</div>'))

You can also specify the name argument for all types other than html which will change the title of the created hyper link:

extra.append(pytest_html.extras.text('some string', name='Different title'))

By default, all tests will have their logs shown except those that have Passed.

This behavior can be customized with a query parameter: ?collapsed=Passed,XFailed,Skipped.

Fork the repository and submit PRs with bug fixes and enhancements, contributions are very welcome.

Tests can be run locally with tox, for example to execute tests for Python 2.7 and 3.6 execute:

tox -e py27,py36

• Release Notes
• Issue Tracker
• Code