pytest-html-reporter 0.3.7

what pytest itself has to be capturing

The reporter can only keep what pytest hands it, and two of pytest’s own options decide that. Neither needs setting for the defaults to work - but if the Logs column is emptier than expected, one of these is why.

Capture. -s (short for --capture=no) sends stdout and stderr straight to the terminal, so pytest never takes them in and no reporter can show them. logging output is unaffected and still appears:

Log level. logging output is captured from WARNING up unless told otherwise, so log.info(...) and log.debug(...) calls will not be in the report until the level is lowered:

$ pytest tests/ --log-level=INFO

Already running with -s? Just remove it. Capture is on by default, so nothing needs to be added in its place:

[pytest]
addopts = -v

The one thing -s gave you that plain capture does not is seeing output in the terminal while the tests run - with capture on, pytest only replays it afterwards, for the tests that failed. If you want both, --capture=tee-sys streams it live and keeps it for the report:

[pytest]
addopts = -v --capture=tee-sys

(Stay on -s if you drop into pdb. And note tee-sys only tees Python’s own sys.stdout / sys.stderr, so if the output you want comes from a subprocess or a C extension, plain fd capture is the one that keeps it.)

the Logs column is empty

Work down this list; the first one that applies is the answer:

1. Is the run using -s or --capture=no? Check addopts in pytest.ini / pyproject.toml / tox.ini, not just the command you typed - a flag set there applies to every run. This is the most common cause, and the report says so above the Test Metrics table when it is happening. Removing the flag is the whole fix; there is no replacement flag to add.

2. Are you on --report-logs=failed while the tests that produce output are passing? That mode keeps output for failed and errored tests only; a passing test shows a dash however much it printed.

3. Is the output logging below WARNING? log.info(...) and log.debug(...) are not recorded until you pass --log-level=INFO or --log-level=DEBUG.

4. Do the tests actually produce any output? A suite of plain assertions prints nothing, and a dash is then the correct answer - a failed test included, since its message is in the Error Message column, not here. Add a print(...) to one test and re-run to confirm the column is working.

The Environment panel states what the run kept and from which log level - e.g. all tests: stdout, stderr and logging, logging from WARNING - so you can always tell which of these you are in.

pytest.ini

Alternate option is to add this snippet in the pytest.ini file:

[pytest]
addopts = -v -rf --capture=tee-sys --title='PYTEST REPORT'
html_report = ./reports/%Y%m%d/report_%H%M.html
archive_count = 7
archive_days = 30
environment = staging
build_info =
    branch=main
    team=payments
    commit=$GITHUB_SHA
    ci=$GITHUB_RUN_ID
report_logs = all
report_log_limit = 10000
report_attachments = all
report_attachment_limit = 20000
report_coverage = auto
report_coverage_limit = 500
report_open = auto
report_link =
    Coverage=htmlcov/index.html
    CI job=https://ci.example.com/job/42

report_logs takes the same values as --report-logs (all / failed / none) and report_log_limit the same as --report-log-limit (a character count, or 0 for no limit). report_attachments and report_attachment_limit mirror --report-attachments and --report-attachment-limit the same way, as do report_coverage, report_coverage_file and report_coverage_limit.

report_open takes the same values as --report-open (auto / always / none), and is the place to turn the browser off once for everybody rather than in every command.

report_link takes one Label=URL per line and, like build_info, adds to whatever --report-link passes rather than being replaced by it.

html_report takes the same value as --html-report, placeholders included, and is the way to set the report location without going through addopts.

archive_count, archive_days and archive_since mirror --archive-count, --archive-days and --archive-since. Retention is a property of the job rather than of one run, so the ini file is usually the better place for it: set it once and every invocation, however it is started, keeps the same window.

Note: --html-report overrides the html_report ini value; --environment overrides the environment ini value; --build-info entries are added to the ones set in the ini file rather than replacing them; --report-link entries are added to the ones set in the ini file the same way; --archive-count, --archive-days, --archive-since, --report-logs, --report-log-limit, --report-attachments, --report-attachment-limit, --report-coverage, --report-coverage-file and --report-coverage-limit override their ini values

Note: If you fail to provide --html-report tag, it consider your project’s home directory as the base

screenshots

Import attach from the library and hand it the PNG bytes of a screenshot. It takes the image itself rather than a browser, so it works with Selenium, Playwright, or anything else that can produce a PNG:

from pytest_html_reporter import attach

attach(data=self.driver.get_screenshot_as_png())   # Selenium
attach(data=page.screenshot())                     # Playwright
attach(data=await page.screenshot())               # Playwright, async API

Note: every image you attach is kept, whatever the test did - a screenshot of a pass is a baseline worth having. Only the tests that actually called attach appear in the gallery, so capturing on failure alone is a matter of deciding when to call it.

attach can be called from anywhere in the test’s lifecycle: the test body, a unittest tearDown, a pytest fixture’s teardown, or a pytest_runtest_makereport hook. Capturing on failure only - the usual want - is the rep_call.failed test in the fixture below; drop it to photograph every test:

# conftest.py
import pytest
from pytest_html_reporter import attach

@pytest.fixture(autouse=True)
def screenshot_on_failure(page, request):
    yield
    if request.node.rep_call.failed:
        attach(data=page.screenshot())

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    rep = outcome.get_result()
    setattr(item, "rep_" + rep.when, rep)

Running Selenium and Playwright side by side? The browser is already in item.funcargs, so one hook covers both at once - no fixture of its own, and nothing to remember in each test. Add a fixture name to the table and that framework is covered too:

# conftest.py
import pytest
from pytest_html_reporter import attach

CAPTURE = {
    "driver": lambda driver: driver.get_screenshot_as_png(),  # Selenium
    "page":   lambda page: page.screenshot(),                 # Playwright
}

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()

    if report.when != "call" or not report.failed:
        return

    for name, capture in CAPTURE.items():
        handle = item.funcargs.get(name)
        if handle is not None:
            attach(data=capture(handle))
            return

This is what tests/functional/conftest.py in this repository does. Drop the report.failed check to photograph every test. The same guidance is printed on the Screenshots tab itself whenever a run captures nothing.

Or attach straight from a hook of your own, which already has the browser in item.funcargs:

# conftest.py
import pytest
from pytest_html_reporter import attach

@pytest.hookimpl(hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    rep = outcome.get_result()

    if rep.when == "call" and rep.failed:
        driver = item.funcargs.get("driver")
        if driver is not None:
            attach(data=driver.get_screenshot_as_png())

Note: put the hook in conftest.py. pytest does pick one up from a test module as well, but only for that module’s own tests - a conftest covers every test under it, which is almost always what you want.

The same hook covers Playwright by reaching for pytest-playwright’s page fixture instead:

page = item.funcargs.get("page")
if page is not None:
    attach(data=page.screenshot())

Note: the hook is synchronous, so Playwright’s async API cannot be photographed from it - there is nowhere to await. With async tests, call attach from the test body instead.

api logs / attachments

See it before you wire anything up - the bundled demo needs no browser and no network:

$ pytest tests/functional/test_attachments.py --html-report=./report

A picture is no use when the thing under test is an API. attach_text, attach_json, attach_api and attach_file take the payloads instead, and everything a test hands over is kept against that test and opened from the new API Logs tab. The Test Metrics table gains a Data column counting what each test attached; clicking it crosses to the tab with the list already narrowed to that one test.

from pytest_html_reporter import attach_api, attach_file, attach_json, attach_text

attach_api(requests.get(url))                         # the whole call
attach_json({"expected": order, "got": response})     # pretty-printed, secrets blanked
attach_text(query, name="Query", format="sql")        # any text at all
attach_file("payloads/order.json")                    # a small file from disk

For example, attaching the JSON response body

attach_json(requests.get("https://reqres.in/api/users/2").json())

def test_creates_an_order():
    response = requests.post(url, json=payload, headers=headers)
    attach_api(response)

    assert response.status_code == 201

# conftest.py
import pytest
from pytest_html_reporter import attach_api

@pytest.fixture
def api(request):
    client = ApiClient()
    yield client

    if request.node.rep_call.failed:
        attach_api(client.last_response)

# lets the fixture above see how the test ended
@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    setattr(item, "rep_" + outcome.get_result().when, outcome.get_result())

attach_api(httpx.get(url))                     # httpx
attach_api(await client.get(url))              # httpx, async API

attach_api(method="POST", url="/orders", status=500,
           request_body=payload, response_body=body, duration=1.4)

attach_api(response, url=upstream_url)         # override just the one field

Authorization: <redacted>
Content-Type: application/json

attach_api(response, redact=False)

attach_text(response.text, name="Response body", format="json")
attach_text(cursor.query, name="Query", format="sql")
attach_text("the third retry is the one that worked")

attach_json({"expected": {"id": 4711}, "got": {"error": "sku unknown"}}, name="Diff")

attach_file("payloads/order.json")
attach_file(har_path, name="Network trace")

# conftest.py
import pytest
from pytest_html_reporter import attach_api

@pytest.fixture
def api(request):
    client = Client()
    yield client
    if request.node.rep_call.failed and client.last_response is not None:
        attach_api(client.last_response)

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    rep = outcome.get_result()
    setattr(item, "rep_" + rep.when, rep)

$ pytest --html-report=./report --report-attachments=failed --report-attachment-limit=5000

test coverage

Run with pytest-cov and the report grows a Test Coverage tab: the overall percentage as a ring, the counts beside it, a row per file with its missing lines, and the percentage plotted across the builds you have kept. A chip on the Dashboard shows the figure and crosses to the tab. Nothing needs configuring - if coverage was measured, it is there:

$ pytest tests/ --cov=my_package --html-report=./report
$ pytest tests/ --cov=my_package --cov-branch --html-report=./report

--cov takes the import name or the path of the code under test - your package, not the tests. Getting that wrong is the one thing that leaves the tab empty after doing everything else right, so the tab says so when it happens rather than showing you a guide to what you just did.

The number is coverage.py’s own, taken through its public API, so the tab and your terminal always agree. With --cov-branch on, branch coverage is folded into it exactly as pytest-cov folds it in, and the table gains a Branches column; without it, that column is dropped rather than filled with zeroes.

Files are listed least covered first, which is the order worth reading and the only defensible way to shorten the list on a large project.

Coverage that was measured somewhere else

The tab does not need pytest-cov to have run in this session. Point --report-coverage-file at a report that already exists - useful in CI, where coverage is often produced by an earlier step:

$ pytest tests/ --report-coverage-file=coverage.xml     # Cobertura, from `coverage xml`
$ pytest tests/ --report-coverage-file=coverage.json    # from `coverage json`
$ pytest tests/ --report-coverage-file=.coverage        # coverage.py's own data file

The kind is worked out from the file’s contents, not its name. A coverage.json or coverage.xml sitting beside the report or at the project root is found without being named at all. A .coverage data file is not picked up that way - one is usually left over from an earlier run, and quietly publishing a number from last Tuesday is worse than publishing none - so name it if you want it. Whichever source is used, the tab says which, and for a file it says when that file was written.

Reading a Cobertura coverage.xml needs no coverage package installed at all, which makes it the useful one when the reporting job is not the job that ran the tests.

Colour, targets and drift

The ring is green at 90% and above, amber at 75%, red below that - unless the project has stated its own bar with --cov-fail-under, in which case that is the line the colour is drawn at and the tab says so. A report should not disagree with the build that just passed or failed beside it:

$ pytest tests/ --cov=my_package --cov-fail-under=80 --html-report=./report

The percentage is written into output.json alongside the test counts, so it travels with the archived builds. That is what gives the tab its +0.8 since the last build and its trend line. A build that ran without coverage leaves a gap in that line rather than a drop to zero.

The annotated source

The one thing a summary cannot replace is the source, line by line, with the missed lines marked. Generate it and the tab links to it:

$ pytest tests/ --cov=my_package --cov-report=html --html-report=./report

It is linked, never embedded. Framing htmlcov into this page would break the property the whole reporter is built on - one file you can mail, publish as a CI artifact or open off a stick - and it would break silently, showing an empty frame wherever the folder did not travel with it. The link is offered only when the folder was written by this run, so an htmlcov left over from last week is not passed off as current.

the Test Coverage tab is empty

Work down this list; the first one that applies is the answer:

1. Did anything measure coverage? pytest-cov has to be installed and --cov passed. With neither, the tab shows the setup guide - which is the correct answer, not a fault.

2. Is --cov pointing at code that actually gets imported? This is the usual one. --cov=src against a project that has no src directory measures nothing at all, and pytest-cov prints Module src was never imported and No data was collected in among the rest of the run. The tab repeats it, naming the flag you typed. Pass your package instead - --cov=my_package, or a path like --cov=./app.

3. Is --report-coverage=none set? Check addopts and report_coverage in pytest.ini / pyproject.toml / tox.ini, not just the command you typed.

4. Is --report-coverage-file pointing at something that is not a coverage report? The tab names the file it could not read.

Whichever source the numbers do come from, the tab states it - Measured by pytest-cov during this run, or Read from coverage.xml, written 2026-08-31 20:23 - so you can always tell which of these you are in.

delta vs the previous build

Once there is a build to compare against, the Highlights card gains a second entry saying which way the suite is moving - ▲ +3 failures over SINCE LAST BUILD, red when there are more failures than last time and green with a ▼ when there are fewer. Nothing to configure; it appears as soon as a second build has been archived.

The absolute count tells you how bad this build is. The delta tells you whether it is getting better, which is the one you act on. Hovering it gives the two counts behind it - 12 failures this build, 9 in the build before it - because +3 reads very differently against 3 than against 300.

Failures here means failures and errors, which is exactly what the Trends chart plots as Failed; both are read off the same per-build list, so the two can never disagree. No change is written ±0 failures rather than 0 failures, which beside SINCE LAST BUILD would say the opposite of what it means. A first build has nothing to compare against, and the whole entry - caption included - is left out rather than showing no change against a build that does not exist.

analytics

The Dashboard answers how did this run go?. The Analytics tab answers how does this test behave?, which no single run can - so it reads every build you have kept and lines them up per test. Nothing to install, nothing to configure, and nothing extra is collected: the archives already hold a status per test per build.

Six figures across the top, then the panels behind them:

• Stability score - one number, 0-100, for how much the suite can be trusted. It starts at the mean per-test pass rate and is charged half the mean flip rate, because a test that alternates pass, fail, pass has the same pass rate as one everybody already knows is broken and is the more expensive of the two to live with. Green at 80, amber at 60, red below it.

• Pass rate this run, with the movement in points since the last build.

• Flaky tests - tests that have flipped between passing and failing, or that needed a retry to pass.

• Always failing - tests that have failed every build they were in, two builds running or more.

• Builds analysed and time in tests, against the median build.

Pass rate across builds plots the drift; the axis is not pinned to 0-100, because a suite that lives between 96% and 99% is exactly the one whose two-point drops matter. What moved, build to build stacks what changed at each step - fixed, regressed, added, dropped. Where the time goes buckets this run’s tests by duration, which a slowest-tests list cannot tell you: two thousand tests at 300ms each is a different problem from ten tests at a minute. Test base growth shows the suite being added to, or quietly shrinking.

Underneath, four cards name what changed since the previous build - newly failing, newly fixed, new tests and no longer run - and then a searchable, sortable row per test: its verdict, its recent outcomes as a strip of one block per build, its pass rate, how many times it has flipped, its retries, how long its current streak has run for and its duration. It opens worst-behaved first, so the list to work through is already the list on screen.

Flaky and always failing are kept apart on purpose. A test that only ever fails is a bug with an owner; putting it at the top of a flakiness list sends somebody hunting a race that is not there. Skips are excluded from the pass/fail arithmetic rather than counted against a test - a test skipped for three builds between two passes has not flipped twice - and a test that has only ever been skipped shows no pass rate at all rather than a rate of zero. xfail and xpass count as passes: they are outcomes the suite declared in advance, and counting them as failures would put every xfail-marked test at the top of the list, where nothing is wrong.

How far back it reads is whatever --archive-count, --archive-days and --archive-since have kept; the charts draw the most recent twenty builds so the axis stays readable, while the tables count every build on disk. On a first run the tab says so and shows the duration panels - which are real from run one - rather than drawing four empty axes.

Per-test durations are recorded into output.json from this version on, so the duration panels fill from the run that produced them; builds archived by an earlier version are read as not measured rather than as instant.

custom side-nav links

--report-link adds an entry to the report’s side nav pointing at any page you like - the annotated coverage source, a CI job, a Grafana board, an internal wiki page. Repeat it as often as you need:

$ pytest tests/ --report-link "Coverage=htmlcov/index.html" \
                --report-link "CI job=https://ci.example.com/job/42"

Relative paths are resolved from wherever the report is written, so linking a folder that ships beside it works. Links open in a new tab. Anything carrying a scheme other than http, https or mailto - javascript: and data:, in practice - is dropped rather than rendered: a report is a build artifact that gets published and passed round, and a nav entry has no business being able to run something in whoever opens it.

parallel runs

Runs distributed with pytest-xdist are gathered into a single report. Every worker sends its results back to the controller, which merges them and writes one report - one build in Archives, one set of totals, one row per test - whichever way the tests were distributed:

$ pytest tests/ -n 2 --html-report=./report
$ pytest tests/ -n auto --dist loadfile --html-report=./report

Tests are listed in collection order rather than the order the workers happened to finish them in, so a parallel report reads the same as a serial one. Nothing needs to be configured, and running without -n is unaffected.

Note: results are handed over when a worker finishes, so tests from a worker that crashes outright (rather than failing) are not in the report - pytest reports the crash itself

Is there a demo available for this gem?

Yes, you can use this demo as an example, https://github.com/prashanth-sams/pytest-html-reporter:

$ pytest tests/functional/