# What Is an HTML Report? — Definition, Structure and Why It Rarely Travels

Canonical: https://commareports.com/glossary/html-report
Published: 2026-09-11

> An HTML report is generated web output presenting the results of a run — tests, coverage, scans, profiles. What is inside one, why it is almost never a single file, and what breaks in transit.

# HTML report

**An HTML report is a web page generated by a tool to present the results
of a run — tests, coverage, a security scan, a profile, an analysis — as
browsable output rather than console text.** It is a build output, not a
hand-authored document, and it is usually interactive.

The category is broad on purpose. A Playwright run, a JaCoCo coverage
tree, a Trivy scan, a Lighthouse audit, an exported Jupyter notebook and
a dbt docs site are all HTML reports: each one is machine-generated,
each one is meant to be read by a person, and each one loses something
essential the moment it is flattened into text or an image.

## What is actually inside one

Almost never a single file. A typical generator emits a directory:

| Part               | Example                       | What happens without it       |
| ------------------ | ----------------------------- | ----------------------------- |
| Entry document     | `index.html`                  | Nothing to open               |
| Stylesheets        | `assets/app.css`              | Unstyled wall of text         |
| Scripts            | `assets/app.js`               | Dead tables, no interactivity |
| Data tree          | `data/test-cases/*.json`      | Empty shell, blank page       |
| Fonts, icons, PNGs | `static/`                     | Broken glyphs, missing charts |
| CDN references     | `<script src="https://cdn…">` | Charts silently absent        |

The data tree is the one that surprises people. Allure, Playwright and
several coverage tools render a shell and then `fetch()` the results —
so the entry file alone is not a degraded report, it is an empty one
([why Allure opens blank](/fix/allure-report-blank-page)).

## The three conditions that only hold locally

1. **The whole directory is present.** Relative references resolve
   because the siblings exist.
2. **The origin is permissive.** A local server gave the page a real
   `http://` origin; opening it from disk gives an opaque `file://`
   origin where `fetch()` is blocked
   ([same-origin policy](/glossary/same-origin-policy)).
3. **The network reaches the CDN.** Yours does. A reviewer behind a
   corporate proxy, or a viewer with a strict
   [Content Security Policy](/glossary/content-security-policy), may not.

Every common "it works on my machine" report failure is one of those
three, and the browser console names which one before any guessing
starts.

## Human report, machine report

Most tools emit both, and both are worth keeping:

- **Machine-readable** — [JUnit XML](/glossary/junit-xml) for tests,
  [SARIF](/glossary/sarif) for findings, lcov or Cobertura for coverage.
  These are for CI gates, code-host annotations and dashboards.
- **Human-readable** — the HTML report. This is the one someone opens
  when the gate fails and they need to know _why_.

Treating the HTML one as a [build artifact](/glossary/build-artifact) is
the common mistake: artifacts are addressed by links that expire under a
[retention policy](/glossary/artifact-retention), which is correct for a
cache and wrong for a document someone will cite in six months.

## Making one readable by other people

Publish the output directory rather than passing the entry file around.
Assets upload alongside the entry HTML with their relative references
rewritten, the page is served over HTTPS from a real origin, and scripts
keep running inside a sandboxed iframe (`allow-scripts`, no
`allow-same-origin`) so sorting, filtering and charts behave as they do
locally ([interactive HTML reports](/interactive-html-reports)).

**Limits:** entry HTML 5 MB; assets 25 MB per file, 250 MB and 500 files
per report.

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history.

**[Publish an HTML report →](https://commareports.com/)**

### Related

- [Share an HTML report](/share-html-report) · [Share an HTML folder](/share-html-folder)
- [Self-contained HTML](/glossary/self-contained-html) · [Build artifact](/glossary/build-artifact)
- [Report types](/report-types) — 200+ per-tool guides · [Glossary](/glossary)