CLI reference

Uses the settings written down under NAME — as [tool.pytest-html-reporter.profiles.NAME] in pyproject.toml, or [pytest-html-reporter.profiles.NAME] in pytest.ini, tox.ini or setup.cfg — so that local and ci are one word each rather than two long command lines kept in two places.

Both files are read, the ini file pytest chose for this run first, and a name defined in both is taken from the ini file whole rather than merged. The name is matched case-insensitively; an unknown one fails the run at configure time, lists the profiles that are defined and offers the nearest.

$ pytest tests/ --report-profile=ci
$ pytest tests/ --report-profile=none     # ignore the pinned default

$ PYTEST_HTML_REPORTER_PROFILE=ci pytest tests/

[pytest]
report_profile = ci

none is the way one run opts back out of a profile the repository pinned as its default — which is why no profile can be called none. Everything the profile settles is written onto the very options the flags parse into, so an xdist worker is shaped by the same profile the controller is, and the Environment panel carries a Profile row naming it.

Prints the settings this run resolved — each one's value, which layer decided it and which layers it overrode — and then runs the suite as usual. The lines go into the pytest header rather than to stdout of their own, because the header is the part of the output that gets pasted into an issue when somebody is asking why their setting did not take.

$ pytest tests/ --report-profile=ci --report-show-config

pytest-html-reporter configuration:
  Profile: ci
  Files read: pytest.ini, pyproject.toml
  Profiles defined: ci, local

  Setting  Value             Source
  ---------------------------------
  path     report/ci         profile 'ci' in pyproject.toml
  logs     failed            profile 'ci' in pyproject.toml
  open     none              profile 'ci' in pyproject.toml
  junit    report/junit.xml  profile 'ci' in pyproject.toml

It is resolved before the profile is applied, which is the only moment the question can be answered: once a profile has been written onto config.option there is nothing left to tell a value somebody typed from a value a profile chose. To ask the same question without running anything, use pytest-html-reporter config.

Where the build is written. The value is expanded through strftime once, at configure time, and then read as either a file or a folder: if the string contains .html anywhere it names a file, and the folder is the part before the last /; otherwise the string names a folder and the file inside it is pytest_html_report.html. ~ and $VARS are expanded and the folder is made absolute.

The resolved folder is the report base, and everything else the build produces lives beside the page: archive/, output.json, pytest_screenshots/ and, on a sharded run, shards/.

$ pytest --html-report=./report                  # ./report/pytest_html_report.html
$ pytest --html-report=./report/index.html       # ./report/index.html
$ pytest --html-report=./reports/%%Y%%m%%d.html  # ./reports/20260903.html

One consequence worth knowing: the previous run's screenshots are swept on every configure by building <raw path>/pytest_screenshots. With a folder path that folder exists and is cleaned. With a file path — ./report/report.html — it looks for ./report/report.html/pytest_screenshots, which does not exist, and nothing is removed.

The report title. The full string is kept for the heading's tooltip; the displayed copy is hard-cut at 20 characters with no ellipsis, and a class on the element tells the page to fade the tail so the cut reads as a cut rather than as a typo.

This is the only option in the group with no ini key. If you want it fixed per project, put it in addopts.

$ pytest --html-report=./report --title="Payments Regression"

Names the environment the suite ran against. It adds an Environment row to the Environment panel and a badge beside the title, cut at 10 characters with the full name in the tooltip.

The value is recorded into each shard's own bundle. A merging leg deliberately passes an empty environment through, so a merged report reports each leg's own value rather than whichever leg happened to run last.

$ pytest --html-report=./report --environment=staging

Adds a row to the Environment panel. Repeat the flag for as many rows as you want. Each entry is split on the first =, so a value may contain more of them; key and value are stripped, a blank entry is skipped, and an entry with no = at all yields an empty value rather than being dropped.

This and --report-link are the two settings that combine with their ini key instead of overriding it. Command-line entries come first, then the build_info lines — so a project can pin team=payments in pytest.ini and let CI add the branch and the run id on top.

$ pytest --html-report=./report \
    --build-info branch="$GITHUB_REF_NAME" \
    --build-info run="$GITHUB_RUN_ID"

Adds one more row to the Environment panel: Packages, holding every installed distribution and its version the way pip freeze reads them, with the count in the label — Packages (214). Names sort case-insensitively, and a distribution whose metadata cannot be read is skipped rather than costing the other two hundred.

It is off by default on purpose. It is a few hundred entries nobody reads until the day the report is the only surviving record of what was installed — and it publishes a full dependency inventory into a file that gets attached to tickets and passed around. The Plugins row answers a much smaller question, and the library whose new minor version broke the suite last night is almost never a pytest plugin.

It is a switch rather than a value, like --report-shard-merge and --report-shard-reset: the flag turns it on, and so does a truthy report_packages ini key (1, true, yes, on). There is nothing on the command line that turns off an ini file which has already said yes. Listing what was installed is a property of the job rather than of one run, so the ini file is usually where it belongs.

$ pytest tests/ --html-report=./report --report-packages

On a sharded run each leg collects the list for itself, on the machine that actually imported those versions. The merged report shows one list when every leg agrees and one row per leg when they do not, which is the case the row exists for.

Adds an entry to the report's side nav. The entry is split on the first =; both halves must be non-empty or the entry is discarded.

Relative paths are kept as they are, because linking ./htmlcov/index.html that sits beside the report is the point of the option. An absolute URL has to carry a scheme of http://, https:// or mailto:; anything else is silently dropped, so a javascript: or data: URL cannot reach a page that gets published and passed around. A one-letter scheme is not treated as a scheme at all, so C:/reports is read as the Windows path it is.

$ pytest --cov=src --cov-report=html --html-report=./report \
    --report-link 'Coverage=htmlcov/index.html' \
    --report-link 'Runbook=https://wiki.example.com/runbook'

Turns a marker into a link on the test it is written on. @pytest.mark.jira("PROJ-123") is already collected and already shown, but as a flat badge, because nothing in the report knows that PROJ-123 is an issue rather than a word. Name the marker here, put {} where its argument goes, and every test carrying it gets a badge that opens the ticket.

The entry is split on the first =, and both halves must be non-empty or it is discarded. A template with no {} is a fixed destination that the marker's presence links to — docs=https://wiki/testing — not an error and not a placeholder somebody forgot.

The id is percent-encoded on the way into the URL, because it is pasted from a tracker and arrives with whatever that tracker allows in one. The template is substituted rather than formatted: str.format reads every brace in a string, and a URL is a place people put them, so a templated Confluence link would throw KeyError instead of rendering. The scheme goes through the same sieve as --report-link, and for a stronger reason — this URL is built per test out of whatever a marker said.

Naming a marker here does two more things. It is registered with pytest, so --strict-markers accepts it and no run prints PytestUnknownMarkWarning for it; and its id is written into the JUnit XML as a <property> on the testcase, which is the half Xray, Zephyr and TestRail actually read. The built-in owner and severity markers need none of this configuration and are written to the XML anyway.

$ pytest --html-report=./report \
    --report-link-pattern 'jira=https://acme.atlassian.net/browse/{}' \
    --report-link-pattern 'testcase=https://acme.testrail.io/index.php?/cases/view/{}' \
    --report-link-pattern 'docs=https://wiki.example.com/testing'

A marker with no pattern keeps the badge it has today, so this is opt-in per marker and nothing changes for a suite that sets none. See markers that link.

Whether the finished report is handed to a browser. auto opens it only when all three of these hold:

• Somebody is sitting thereThe original stdout is a tty. pytest replaced sys.stdout with a capture long ago, so a run piped into a log file or started by cron is correctly read as unattended.
• It is not a build agentSeventeen environment variables are consulted; see Environment variables below.
• There is a graphical sessionAssumed on macOS and Windows; on anything else DISPLAY or WAYLAND_DISPLAY has to be set. Without this check, webbrowser on a headless Linux box falls through to a console browser and opens the report in the terminal, on top of the summary the run just printed.

The report is opened as a file:// URL with new=2, which asks for a tab rather than a window so a run in a loop does not bury the desktop. Every failure path is swallowed: the tests are over and the report is written by the time any of this runs, and a machine with no browser on it is not a failed build.

$ pytest --html-report=./report --report-open=none     # never
$ pytest --html-report=./report --report-open=always   # even in a container

How many builds the Archives section shows and keeps on disk. This is handled as text rather than as a number, because empty and 0 are different answers and both get asked about later:

A non-integer is a usage error — --archive-count takes a number of builds to keep, not 'nine' — and so is a negative number.

$ pytest --html-report=./report --archive-count=20

Keep only the builds run in the last DAYS days; older archived builds are deleted. Fractions are allowed, so 0.5 is twelve hours — useful on a suite that runs on every commit rather than nightly.

A non-numeric value is a usage error, and so is a negative one.

$ pytest --html-report=./report --archive-count=50 --archive-days=14

Delete every archived build older than DATE. Three formats are tried in order: %Y-%m-%d %H:%M:%S, %Y-%m-%d %H:%M, then %Y-%m-%d. All are read in local time, so a bare date means midnight local. Anything else is a usage error naming the two shapes it accepts.

Use this for a hard line — the day a release branch was cut, the day a flaky suite was rewritten — where a rolling window of days would keep sliding past it.

$ pytest --html-report=./report --archive-since='2026-06-01 09:00'

Whose captured stdout, stderr and logging output is kept. none is more than a display setting: it stops the reporter collecting sections in pytest_runtest_makereport at all, so nothing is buffered in the first place.

Sections are keyed by pytest's own section title and the last write wins, so a test retried by pytest-rerunfailures shows the attempt actually being reported rather than every attempt's output stacked up.

$ pytest --html-report=./report --report-logs=failed

The maximum number of characters of captured output kept per test, counted across all of that test's sections. 0 keeps everything, and so does any negative number.

The tail is what survives, because logs read chronologically and the interesting part of a log is the end. The cut is made at a line boundary rather than mid-line, and a synthetic Trimmed section is prepended reading N earlier characters dropped - raise --report-log-limit to keep them., so the page never quietly pretends the output was that short.

$ pytest --html-report=./report --report-logs=failed --report-log-limit=0

Whose attachments are kept — the payloads handed to attach_text(), attach_json(), attach_file() and attach_api(). These are things the suite asked for by name, which is why the default is all; drop to failed when an API-heavy suite is making the page large.

Images handed to attach() are not attachments in this sense and are governed by nothing — see --report-screenshots. The functions themselves are documented in the Python API.

$ pytest --html-report=./report --report-attachments=failed

Maximum characters kept per attached payload. 0 — and any negative value — keeps everything. The limit is per payload, not per test, so a test that attaches six responses can carry six times this much.

$ pytest --html-report=./report --report-attachment-limit=50000

When the reporter photographs a live Selenium driver or Playwright page without the suite asking. The picture is taken in pytest_runtest_teardown, before the fixture finalizers run and close the browser, which is the last moment the page still exists.

The default is failed because photographing a run that passed produces a great many pictures of pages that were fine, and every one of them costs a round trip to the browser.

$ pytest tests/ui --html-report=./report --report-screenshots=all

More about how the picture is taken, and about attaching your own, in Screenshots.

Whose test steps are kept — both the pieces named with step() and the Given/When/Then of a pytest-bdd scenario.

The default is all rather than failed, unlike a log, because the steps of a test that passed are what a later failure gets read against, and they cost a line each.

$ pytest --html-report=./report --report-steps=failed

Steps and BDD covers what a step tree looks like.

Maximum steps kept per test. 0 keeps every one, and so does any negative value, which is clamped to 0 — enforcement is if limit() and len(steps) >= limit(), and a falsey limit never fires.

This one is stored on class-level config state rather than on the reporter, because step() is called by the test long before the reporter object is reachable from it. What it is for: a step called inside a ten-thousand-row loop would otherwise write ten thousand lines into the page, and the tree stops being readable long before it stops being generated.

$ pytest --html-report=./report --report-step-limit=0

Whether the Coverage tab is built at all. none switches it off, including the coverage entry in output.json — so the number is not archived and does not appear on the trend either.

$ pytest --cov=src --html-report=./report --report-coverage=none

Read coverage from this file instead of discovering one. Three kinds are understood, detected from the contents rather than the extension: a coverage.py coverage.json, a Cobertura coverage.xml, and a .coverage data file.

With no file named, discovery looks for coverage.json and then coverage.xml. Name the file when the coverage was measured somewhere else — a previous job, a different container — and the file you want is not the one discovery would find first.

$ pytest --html-report=./report --report-coverage-file=./artifacts/coverage.xml

How many files the Coverage tab lists, least-covered first. 0 — and any negative value — lists every one. The order is what makes a limit tolerable here: the files a limit cuts off are the ones already well covered.

$ pytest --cov=src --cov-report=json --cov-fail-under=85 \
    --html-report=./report \
    --report-coverage-file=./coverage.json \
    --report-coverage-limit=0

Names this process as one leg of a sharded run — 1/4, e2e, py311-linux. The leg writes its records to <report>/shards/<id> and no report of its own.

The id has to be a directory name, so it is sanitised: anything outside [A-Za-z0-9._-] becomes -, runs of - collapse to one, - and . are stripped from both ends, and the result is truncated to 64 characters. The raw value is what travels into the bundle as the shard's label, because 1/4 reads better in the report than 1-4.

An id that sanitises to nothing — .., // — is a usage error rather than a silent fallback. Both . and .. are made entirely of characters the pattern considers safe, and a shard directory that resolved to the report base itself would empty the report's screenshots and drop its bundle in the wrong place.

$ pytest tests/unit --html-report=./report --report-shard=1/4

After writing this leg's bundle, merge every bundle beside it and render one report. This is for sequential legs on one machine: three runs need three commands rather than four.

It requires --report-shard — a merging leg still has to say which leg it is — and the run aborts at configure time if it is missing. A merge failure after the tests is written to stderr and the leg returns without a report rather than raising an internal error once every test has already passed; the bundles stay on disk for pytest-html-reporter merge to pick up. Every bundle that was merged is named on stderr with the time it finished.

$ pytest tests/unit        --html-report=./report --report-shard=unit --report-shard-reset
$ pytest tests/integration --html-report=./report --report-shard=integration
$ pytest tests/e2e         --html-report=./report --report-shard=e2e  --report-shard-merge

The ini form takes 1, true, yes or on, case-insensitively; anything else is false.

Names the CI run this leg belongs to. The token is stamped into every bundle, and a merging leg merges only the bundles carrying the same token — the ones it puts aside are named on stderr, along with advice to clear the folder or give the first leg --report-shard-reset.

When nothing is given, the token is derived from the CI system's own variables (see the table below). A leg with no token at all merges everything, which is what the feature has always done.

$ pytest --html-report=./report --report-shard=1/4 \
    --report-shard-run="$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"

Delete <report>/shards entirely before this leg writes into it. For the first leg of a sequential run, where the legs share one persistent --html-report and the folder accumulates: a leg renamed or dropped since the last run would otherwise leave a bundle behind that the next merge reports as part of this build — six tests when four ran.

It is applied before the leg's own directory is dealt with, since it takes that directory with it.

$ pytest tests/unit --html-report=./report --report-shard=unit --report-shard-reset

Also write a JUnit XML of this run to PATH, for a CI system that reads XML. Date and time placeholders are expanded exactly as they are for --html-report.

The XML is written before the guard that skips a run which collected nothing, deliberately: a run that collected nothing still owes its CI system a document saying so, because a missing file reads as "the job never ran".

A write failure is reported on stderr as pytest-html-reporter: --report-junit could not write <path>: <error> and never raises. The run has already finished, and losing the HTML report, output.json and the archived build over a mistyped XML path would be the wrong trade.

$ pytest --html-report=./report --report-junit=./report/junit-%%Y%%m%%d.xml

How an unexpectedly passing test is written down. pass is what pytest's own --junitxml does.

This is the only shaping flag a pytest run has for the XML. The equivalents of --junit-suite-name, --junit-hostname, --junit-logging and --junit-attachments exist only on the standalone command below.

A value outside the three is a usage error rather than a fallback, and that is on purpose: the default is the one answer a team that reached for this flag was trying to avoid.

$ pytest --html-report=./report --report-junit=./junit.xml --report-junit-xpass=fail

Directories to search for shard bundles, or records.json files named directly. The everyday shape is one folder holding the artifacts four CI jobs uploaded, and the everyday command is run from inside it — which is why the default is the current directory.

Discovery expands ~ and $VARS, takes a named file as-is, and otherwise walks a directory collecting every records.json. Subdirectories and candidates are sorted at every level, so the same folder yields the same list twice running, and results are deduplicated by absolute path.

A file that is not a bundle — the wrong schema, or not JSON at all — is skipped with a note. A bundle written by a newer pytest-html-reporter is a different matter: it stops the merge and is named, rather than being read hopefully, because silently dropping a quarter of a matrix produces a report that is wrong in a way nobody looking at it can see.

Bundles are ordered by a natural sort of the shard id, then the id, then the file path — never load order — so two CI jobs downloading the same four artifacts in different orders produce the same report.

$ pytest-html-reporter merge ./artifacts --html-report ./report
$ pytest-html-reporter merge ./artifacts/shard-1/records.json \
    ./artifacts/shard-2/records.json --html-report ./report

What to do when one nodeid ran in more than one shard — a badly split matrix, or a leg re-run over the top of another.

Every fold is reported on stderr whichever policy is chosen.

$ pytest-html-reporter merge ./artifacts --html-report ./report --on-duplicate error

Row order. shard keeps each suite's rows in shard order, which is the order they ran in. name sorts by suite and test name, which is what you want when the report is being diffed against yesterday's by eye.

$ pytest-html-reporter merge ./artifacts --html-report ./report --order name

Strip this prefix from the front of every nodeid, so shards that ran under different checkout roots group into one suite instead of four. Applied after separators are normalised — backslashes become slashes, repeated slashes collapse, a leading ./ is removed — so one prefix covers a Windows leg and a Linux leg.

A prefix that would swallow a whole nodeid is not applied to it: the original id is worth more than an empty one, which would be quarantined.

$ pytest-html-reporter merge ./artifacts --html-report ./report \
    --strip-path-prefix /home/runner/work/repo/ \
    --strip-path-prefix /src/

Where the merged report is written: a folder, or the .html file itself. Two values are refused — an empty or whitespace one, and a path with .html in it that does not end in .html, which the render pipeline would read as a file name and drop into the current directory. The run has already happened by the time anybody goes looking for the report, so this one is refused rather than obeyed.

Pointing the merge at the same folder the shards wrote into is safe. The merge clears <base>/pytest_screenshots before staging images, while every shard's copies live on under <base>/shards/<id>/pytest_screenshots.

$ pytest-html-reporter merge ./report --html-report ./report   # safe
$ pytest-html-reporter merge ./artifacts --html-report ./my.html.d
pytest-html-reporter: --html-report './my.html.d' has '.html' in it without ending in it, ...

The moment this build is filed under. It names the archive file, stamps output.json, labels the trend point, orders builds in Analytics, and dates the build — so a matrix that started before midnight and merged after it is dated the day it ran, not the day it finished being collected.

It is validated up front, before --dry-run too, so a typo is reported rather than a build promised that could not have been stamped.

$ pytest-html-reporter merge ./artifacts --html-report ./report --start-time now

.coverage data files, or directories holding them, to combine into the merged build's Coverage tab. A directory contributes every entry whose name starts with .coverage, sorted.

The files are copied into a temporary directory before being combined, because coverage.combine() deletes what it reads — and those are somebody's CI artifacts, very often the only copy.

If the coverage package is not installed in the merging environment, or nothing matched, or the combine failed, the merge still succeeds and reports a notice instead. Losing the whole report over a coverage number would be the wrong trade.

$ pip install coverage
$ pytest-html-reporter merge ./artifacts --html-report ./report \
    --coverage-data ./artifacts --coverage-target 85

Copy the screenshots the merged records name into the report, prefixing each with the shard that took it. The prefix is not cosmetic: screenshot names restart their counter in every process, so two machines' first screenshots would otherwise collide.

Staging is also what discovers that an image a bundle named is not in the bundle. Those are reported as missing screenshots and feed --strict. --no-copy-assets leaves the images in the shard folders, which means the report's links only resolve where those folders are.

$ pytest-html-reporter merge ./artifacts --html-report ./report --no-copy-assets

Where the merged JUnit XML is written. Unlike merge, a write failure here means the one thing this subcommand exists to produce was not produced, so it exits 2 with no summary.

Screenshots are renamed exactly as a merge would rename them while copying — each prefixed with its own shard, not the row's, because the duplicate policy can back-fill one shard's screenshots onto another shard's record. Attachment lines therefore use the same relative paths the HTML page uses, which is correct whenever this XML sits beside a report merged from the same bundles.

$ pytest-html-reporter junit ./artifacts \
    -o ./results/merged-junit.xml \
    --junit-suite-name payments \
    --junit-logging failed \
    --junit-xpass fail \
    --strict

Print the same thing as a JSON document on stdout, indented and with sorted keys. It carries a bundles array — id, label, path, hostname, platform, python, pytest, exitstatus, session_start, session_end, records, collect, coverage — and a summary object with shards, tests, collects, statuses, reruns, duplicates_folded, quarantined, unreadable, superseded, unrecognised, session_start, session_end, wall, hosts, environment, coverage_notice and notes.

The reason to ask for JSON is that something downstream is going to check four shards arrived and none of them was empty. Notes stay on stderr precisely so this stays a document.

$ count=$(pytest-html-reporter inspect ./artifacts --json \
    | python -c 'import json,sys; print(json.load(sys.stdin)["summary"]["shards"])')
$ test "$count" -eq 4 || { echo "only $count shards arrived"; exit 1; }

They answer two different questions and are deliberately separate. --strict is a verdict about the merge being complete; --exit-code is a verdict about the tests. Either way the report is written: a merge that exits 1 has still produced the page that explains why.

$ pytest-html-reporter merge ./artifacts --html-report ./report --strict --exit-code
$ echo $?