pytest-html-reporter 0.3.6

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_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_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.

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/