Introduction

pytest-html is one of the most popular PyTest plugins used for generating HTML reports for automated test execution. It creates detailed, browser-friendly reports that display information such as passed tests, failed tests, skipped tests, execution time, and error messages.

When integrated with Selenium automation frameworks, pytest-html provides an easy way to share test results with developers, testers, and stakeholders. Instead of reading console output, teams can simply open the generated HTML report in a browser and review the execution summary.

In this tutorial, you’ll learn what pytest-html is, why it is used, how to generate reports using it, along with practical examples, real-world scenarios, common mistakes, and best practices.

What is pytest-html?

pytest-html is a PyTest plugin that generates HTML reports from test execution results.

It provides information such as:

Passed test cases
Failed test cases
Skipped tests
Execution duration
Error messages
Test execution summaries
Browser-friendly output

The generated reports can be:

Shared with team members
Integrated into CI/CD pipelines
Archived for future reference
Used for debugging automation failures

Why Use pytest-html?

pytest-html helps you:

Generate professional HTML reports.
Improve automation visibility.
Simplify debugging.
Share execution results easily.
Integrate reporting with CI/CD pipelines.
Improve automation maintainability.

Installing pytest-html

Install the plugin using:

pip install pytest-html

You can verify the installation using:

pip show pytest-html

If the plugin is installed successfully, PyTest will recognize the HTML reporting parameters automatically.

Common Command-Line Options

Command	Purpose
–html=report.html	Generates an HTML report
–self-contained-html	Creates a standalone report
-s	Displays console output during execution
pytest test_file.py	Executes the specified test file

Example

The following example verifies that the pytest-html plugin is installed successfully.

import pytest_html


# Topic: 51. Test Reporting - pytest-html
# Practice site: n/a (plugin example)
# Run: pytest -s 51_examples/test_02_pytest_html.py --html=reports/pytest_html_report.html --self-contained-html
#
# pytest-html generates the report when you pass --html=<path>.


def test_pytest_html_plugin_installed():
    assert pytest_html.__name__ == "pytest_html"

Output

================= test session starts =================

1 passed in 0.05s

Generated HTML report:

reports/pytest_html_report.html

======================================================

The generated HTML report contains information such as:

Total tests executed
Passed tests
Failed tests
Execution duration
Test execution summary

Note: pytest-html generates reports only when the --html parameter is provided during test execution.

Running the Test

Execute the following command:

pytest -s 51_examples/test_02_pytest_html.py --html=reports/pytest_html_report.html --self-contained-html

Understanding the Command

pytest

Executes the PyTest test suite.

-s

Displays console output during execution.

--html=reports/pytest_html_report.html

Generates the HTML report at the specified location.

--self-contained-html

Creates a standalone HTML report that can be shared easily without additional resources.

Understanding the Code

Import the pytest-html Plugin

import pytest_html

This imports the installed pytest-html plugin.

If the plugin is not installed, Python raises an ImportError during execution.

Verify the Plugin Name

assert pytest_html.__name__ == "pytest_html"

This assertion verifies that:

The plugin is installed successfully.
Python is able to import it correctly.
The imported module name matches the expected value.

If the assertion succeeds, the test passes successfully.

How pytest-html Works

Execute PyTest
       │
       ▼
Load pytest-html Plugin
       │
       ▼
Execute Test Cases
       │
       ▼
Collect Test Results
       │
       ▼
Generate HTML Report
       │
       ▼
Store Report File
       │
       ▼
Open Report in Browser
       │
       ▼
View Execution Summary

The plugin automatically collects test execution information and generates the HTML report once the test run completes successfully.

Practical Example

Suppose an e-commerce website contains:

Login tests
Search functionality tests
Cart validation tests
Payment workflow tests

After executing hundreds of automated test cases, the automation framework generates an HTML report using pytest-html.

The report provides:

Pass percentages
Failed test information
Execution summaries
Overall automation health

This significantly improves test result analysis.

Automation Testing Example

Consider an online banking application containing:

Account management tests
Fund transfer validations
Statement generation tests
Security validation tests

The regression suite executes several hundred test cases across multiple environments.

Using pytest-html, the framework automatically generates reports such as:

Smoke_Report.html

Regression_Report.html

Cross_Browser_Report.html

These reports can immediately be shared with:

Test Engineers
Developers
Project Managers
Stakeholders

Real-World Example

pytest-html is widely used in:

Banking applications
E-commerce websites
Healthcare portals
CRM systems
Government applications
Enterprise web applications
CI/CD pipelines

It is one of the most commonly used reporting plugins in Selenium and PyTest automation frameworks.

Advantages of pytest-html

Easy to install.
Generates browser-friendly reports.
Integrates seamlessly with PyTest.
Improves debugging.
Supports CI/CD integrations.
Easy to share with team members.

Common Mistakes Beginners Make

Forgetting to Install the Plugin

Always install the plugin before using:

pip install pytest-html

Without installation, PyTest cannot generate HTML reports.

Forgetting the HTML Parameter

Instead of writing:

pytest test_file.py

prefer:

pytest test_file.py --html=report.html

Otherwise, no HTML report will be generated.

Forgetting Self-Contained Reports

Prefer using:

--self-contained-html

because it creates standalone reports that are easier to archive and share.

Ignoring Report Information

Many beginners generate reports but review only the pass/fail status.

Always examine:

Failure messages
Execution duration
Error details
Test statistics
Overall execution summaries

to improve debugging efficiency.

Best Practices

Install and configure pytest-html properly.
Generate reports for every automation execution.
Use self-contained HTML reports whenever possible.
Store reports inside dedicated report folders.
Archive important execution reports.
Integrate reporting with CI/CD pipelines.
Review failure details carefully before debugging automation failures.

Conclusion

pytest-html is a powerful and lightweight reporting plugin that simplifies the process of generating HTML reports in Selenium automation frameworks. By combining PyTest, Selenium, and pytest-html, teams can easily visualize execution results, improve debugging efficiency, and share test reports across development and testing teams. Proper reporting practices greatly improve the maintainability and visibility of modern automation projects.

Frequently Asked Questions (FAQs)

What is pytest-html?

pytest-html is a PyTest plugin used to generate browser-friendly HTML reports from test execution results.

How do I install pytest-html?

Use:

pip install pytest-html

Can pytest-html generate standalone reports?

Yes.

Using:

--self-contained-html

creates standalone reports that are easy to share and archive.

Is pytest-html commonly used in Selenium automation frameworks?

Yes.

It is one of the most widely used reporting plugins for Selenium with PyTest automation projects.

Can pytest-html be integrated with CI/CD pipelines?

Yes.

It integrates seamlessly with various CI/CD workflows and helps teams visualize automation results efficiently.

Key Takeaways

pytest-html is a popular PyTest plugin for generating HTML reports.
It provides browser-friendly summaries of test execution results.
Reports include pass/fail statistics, execution summaries, and debugging information.
The --html parameter specifies the report location.
--self-contained-html creates portable standalone reports.
pytest-html integrates well with Selenium automation frameworks and CI/CD pipelines.
Proper report generation practices significantly improve automation visibility and maintainability.