HTML Test Runner

1.2.1 · maintenance · verified Thu Apr 16

html-testRunner is a Python unittest test runner that generates human-readable HTML reports for test results. It extends the standard library's unittest module to provide clear and organized visual output. The current version is 1.2.1, released in September 2019. The project currently has an infrequent release cadence, with the latest update several years ago, and is considered to be in a maintenance state.

Common errors

```
ModuleNotFoundError: No module named 'HtmlTestRunner'
```
cause This error typically indicates that the `html-testrunner` package was either not installed correctly, or the Python environment running the code cannot find it. This can also happen if a different, similarly named package was installed instead, or if the import statement is incorrect.

fix Ensure the package is installed: `pip install html-testrunner`. Verify the import statement is `from HtmlTestRunner import HTMLTestRunner`. If using an IDE, ensure the correct Python interpreter is selected for the project. For older versions, direct download and placement of the `HTMLTestRunner.py` file was common, which can cause module resolution issues if not handled properly.
```
AttributeError: 'dict' object has no attribute 'has_key'
```
cause This error occurs when running older versions or legacy standalone `HTMLTestRunner.py` files with Python 3.x. The `dict.has_key()` method was removed in Python 3; its functionality is replaced by the `in` operator.

fix Upgrade to the officially maintained `html-testrunner` package (version 1.2.1) via `pip install --upgrade html-testrunner` which should contain Python 3 compatible code. If using a standalone `HTMLTestRunner.py` file, ensure it's a Python 3 compatible version or switch to the pip-installed package. Alternatively, use a modern fork like `HTMLTestRunner-rv` or `HtmlTestRunner-Ably`.
```
HTML report not generated (no file created) or empty report.
```
cause Common causes include incorrect indentation of the `if __name__ == '__main__':` block, preventing the `runner.run()` call from executing. It can also be due to an incorrect `output` path that the Python process doesn't have write permissions for, or an issue with the test suite itself not loading any tests.

fix Check that the `if __name__ == '__main__':` block and the code within it are correctly indented and will execute. Ensure the `output` directory specified in `HTMLTestRunner(output=...)` exists and the Python process has write permissions to it. Add `print()` statements to trace execution flow and verify that `runner.run(suite)` is being called.

Warnings

breaking The original `html-testrunner` (version 1.2.1 and earlier) may exhibit compatibility issues or unexpected behavior with Python 3.10 and newer versions, particularly concerning exception handling.
Fix: Consider using community-maintained forks like `HtmlTestRunner-Ably` (pip install HtmlTestRunner-Ably) or `HTMLTestRunner-rv` (pip install HTMLTestRunner-rv) if you are encountering issues with newer Python versions, as these forks often include fixes and modernizations not present in the original package.
gotcha The `html-testrunner` package has not seen significant updates since its 1.2.1 release in 2019. This means it might not address newer Python features, modern web browser rendering issues, or include recent bug fixes present in more actively developed test runner alternatives.
Fix: For projects requiring active development, broader compatibility, or more modern features and styling, explore alternative or forked HTML test runners such as `HTMLTestRunner-rv` or `pytest-html` (for pytest users).
gotcha Due to several similarly named packages on PyPI (e.g., `HTMLTestRunner-rv`, `HTMLTestRunner-Python3`, `HtmlTestRunner-Ably`), users might accidentally install a different, potentially incompatible, version when attempting to use the `html-testrunner` package. Ensure you are installing the correct package based on your project's requirements.
Fix: Always verify the exact package name (`pip install html-testrunner`) and check the PyPI project page for the specific version and maintainer you intend to use.

Install

pip install html-testrunner Install latest version

Imports

HTMLTestRunner
wrong:
```
import HTMLTestRunner
```
correct:
```
from HtmlTestRunner import HTMLTestRunner
```
The class `HTMLTestRunner` is nested within the `HtmlTestRunner` package, requiring a direct import from the package, not as a top-level module.

Quickstart

This quickstart demonstrates how to set up a basic `unittest.TestCase` suite and run it using `HtmlTestRunner.HTMLTestRunner` to generate an HTML report. The report will be saved in a 'reports' directory, which is created if it doesn't exist.

import unittest
from HtmlTestRunner import HTMLTestRunner
import os

class MyTests(unittest.TestCase):
    def test_success_case(self):
        """This test should pass."""
        self.assertEqual(1, 1)

    def test_failure_case(self):
        """This test should fail."""
        self.assertEqual(1, 2)

    def test_error_case(self):
        """This test should raise an error."""
        raise ValueError("Deliberate error for testing")

    @unittest.skip("demonstrating skipping")
    def test_skipped_case(self):
        """This test should be skipped."""
        self.fail("Should not run")

if __name__ == '__main__':
    # Ensure a 'reports' directory exists
    output_dir = 'reports'
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    suite = unittest.TestSuite()
    suite.addTest(unittest.makeSuite(MyTests))

    # Run the test suite with HTMLTestRunner
    runner = HTMLTestRunner(output=output_dir, report_name="MyTestReport")
    runner.run(suite)
    print(f"HTML report generated in {output_dir}/MyTestReport.html")

view raw JSON →