Prashanth sams

Posted on Oct 3

3.1+ Million Downloads of pytest-html-reporter 🚀

#opensource #python #testing #automation

Six years after its first release, the pytest plugin that turns a test run into one shareable HTML file has had its biggest update yet.

A test run finishes with a few failures. Before you can fix anything, you need to find the affected tests, read the errors, and work out what changed since the last build.

That is where a good test report earns its place.

Today, I'm excited to share a milestone: pytest-html-reporter has reached 3.1 million downloads. 🎉

I published the first version in July 2020. Since then, it has run on laptops and CI servers I will never see, for teams I have never met. As the project's creator and maintainer, I'm grateful to everyone who has installed it, reported a bug, shared feedback, or contributed an improvement.

The goal remains simple: help teams understand their pytest results quickly, so they can get on with fixing the problems those results reveal.

One file. The whole test run.

pytest-html-reporter is a pytest plugin. Install it, and your usual pytest run writes a single, self-contained HTML report. There is no second tool to render it and no dashboard server to host it. You can email the file, attach it to a ticket, or publish it as a CI artifact.

On your own machine, the report opens in your browser as soon as the run ends. On CI, it doesn't try.

A 38-second tour: dashboard, analytics, test metrics, steps, archives, screenshots, API logs and coverage.

The biggest update yet

If you last tried pytest-html-reporter a few years ago, it looks very different today. The 0.3 and 0.4 releases rebuilt the report and added most of what you'll see below.

Here's a quick tour, in the order you might use it when a build goes red.

Start with the dashboard

The dashboard in light and dark. The report follows your system theme until you pick one, then remembers your choice.

The dashboard shows the run at a glance: totals, pass rate, duration, trends across builds, and highlights such as the most failed suite and the change in failures since the last build.

Every status count is a link. Click 28 FAILED, and the report opens Test Metrics filtered to exactly those tests.

Go from a number to the failing tests

Test Metrics: every test as a searchable, sortable row you can export to CSV or Excel.

Each test gets one row with its suite, status, duration, error message, logs, steps and screenshot. A retried test stays one row with the outcome that stuck. Open its rerun count to see what each attempt failed with.

Every row also has a permanent link that opens the report at that exact test, and filters live in the URL too (#test-metrics?status=FAIL). "The failures in last night's build" becomes a link you can paste into a ticket or a chat.

See what the test saw

Failing Selenium and Playwright tests are captured automatically, and every image lands in one gallery.

When a Selenium or Playwright test fails, the reporter takes a screenshot automatically. You don't add a hook, a fixture or an import. Every picture the run took also appears in one gallery, beside its suite and error.

API Logs: the request and response behind each test, with the curl command that repeats the call.

For API tests, you can attach requests, responses, JSON, text and files to the test that produced them. The API Logs page shows each call with its status and timing, gives you the curl command to replay it, and blanks out credentials before they reach the report. Captured stdout, stderr and logging output are kept with each test as well.

Follow the steps

Test Steps: named, timed steps for every test, with pytest-bdd scenarios shown as Given, When and Then.

Name the steps inside a test, and the report shows each one with its timing, nested from the suite down to the action. This works for async tests, too. pytest-bdd scenarios need no changes at all: their Given, When and Then steps appear individually, and the failing step carries its error and screenshot.

Spot the patterns

Analytics across 21 archived builds: stability score, flaky tests, failures grouped by exception, and ownership.

One run tells you what broke. History tells you whether it matters. The reporter archives every build, so Analytics can score the suite's stability, separate flaky tests from tests that always fail, group failures by the exception behind them, and show pass-rate drift and where the time goes.

Add the built-in owner and severity markers to your tests, and failures are broken down by team and priority, too.

Check the coverage

The Test Coverage tab: overall and per-file coverage, missing lines, and the trend across builds.

When pytest-cov runs, a Test Coverage tab appears with overall and per-file coverage, missing lines and the trend across builds. Coverage measured in an earlier CI job can be brought in, too.

Built for CI, too

The same plugin works from a laptop up to a large pipeline:

Parallel runs: a pytest-xdist run produces one report, not one per worker.
Sharded runs: pytest-html-reporter merge combines shards from several machines into one build, one set of totals and one JUnit XML file.
JUnit XML: written by the same run, for your CI's test results view.
Named profiles: keep local and ci settings in pyproject.toml and pick one with --report-profile=ci.
Environment details: the host, Python and plugin versions, CI system, branch and commit are recorded automatically, with a link back to the pipeline.

Try it on your next test run

If you already have a pytest suite, install the package and run your tests:

pip install pytest-html-reporter
pytest

That's all it takes. The report is written to report/pytest_html_reporter.html and opens when the run finishes. To choose where it goes and what it's called:

pytest tests/ --html-report=./report/report.html --title="Test Results"

On GitHub Actions, one step installs the plugin, runs pytest, and publishes the results to the job summary, a pull request comment that updates on every push, and a downloadable artifact:

steps:
  - uses: actions/checkout@v4
  - uses: prashanth-sams/pytest-html-reporter-action@v1
    with:
      python-version: '3.12'
      requirements: requirements.txt
      tests: tests/

In VS Code, the Pytest HTML Reporter extension lists failing tests by suite in the sidebar. Click one to jump to its def, or open the full report in an editor tab:

code --install-extension prashanth-sams.pytest-html-reporter-vscode

Explore the documentation and live demo →

Thank you to our sponsor, PickOH

pytest-html-reporter is sponsored by PickOH. PickOH lets you map the countries you have visited, plan trips, and join destination communities for weather, tips and attractions, all for free.

Their support helps keep this plugin free, open source and actively maintained. If the reporter has saved you time, take a look at what they're building at pickoh.com.

Thank you for helping the project grow

Reaching 3.1 million downloads is an encouraging moment. Maintaining a useful project means continuing to listen, fix issues and make everyday workflows easier.

If pytest-html-reporter has helped your work, I'd love to hear how you use it and what would make it better. The roadmap is public, and issues and pull requests are always welcome.

Try it on your next build. Share your feedback. And if you find it useful, give the project a star on GitHub. ⭐

GitHub · PyPI · Live demo · GitHub Action · VS Code extension

Prashanth Sams — Creator and maintainer of pytest-html-reporter