Karma HTML Reporter

Sometimes a plain XML file or terminal log isn't the most useful artifact — a browsable HTML report is easier to share with non-technical stakeholders or archive for later review. This lesson covers generating one from Karma.

Generating an HTML Test Report

An HTML reporter plugin (such as karma-htmlfile-reporter) writes a single self-contained HTML file summarizing every spec, its result, and any failure details — viewable directly in a browser with no extra tooling required.

npm install --save-dev karma-htmlfile-reporter

// karma.conf.js
config.set({
  reporters: ['progress', 'html'],
  htmlReporter: {
    outputFile: 'reports/tests.html',
    pageTitle: 'Karma Test Results',
    groupSuites: true,
    useCompactStyle: true
  }
});

The generated file is a normal, static HTML document — no server is needed to view it, just open it in any browser.

Common htmlReporter Options

htmlReporter: {
  outputFile: 'reports/tests.html',
  pageTitle: 'My Project Test Results',
  subPageTitle: process.env.CI ? 'CI Run' : 'Local Run',
  groupSuites: true,
  useCompactStyle: true,
  useLegacyStyle: false
}

groupSuites: true organizes results visually by their describe() hierarchy in the generated page.
subPageTitle is a good place to inject dynamic context, like the CI build number or branch name.
useCompactStyle: true reduces visual clutter for very large suites with many specs.
The generated HTML file has zero runtime dependencies once written — it's fully self-contained.

HTML Reporter Cheat Sheet

Key settings and typical CI usage patterns.

Setting / Use Case	Detail
`outputFile`	Path the self-contained HTML report is written to
`pageTitle`	Title shown at the top of the generated report
`groupSuites`	Organizes results by describe() hierarchy
Archiving as a CI artifact	Upload the file alongside JUnit XML for human review
Sharing with non-technical stakeholders	The HTML file needs no tooling to view

HTML Reports vs. JUnit XML: Different Audiences

JUnit XML is optimized for machine consumption — CI dashboards parse it into charts and trend graphs. An HTML report is optimized for a human opening the file directly, especially someone who doesn't have (or want) direct CI dashboard access.

Generate both in CI when both audiences (dashboards and humans) matter.
HTML reports work well as a build artifact attached to a release or QA sign-off process.
Unlike JUnit XML, HTML reports aren't typically parsed by other tooling — they're a terminal artifact for reading, not integration.

Archiving Reports as CI Artifacts

Most CI platforms support uploading arbitrary files as build artifacts, which is exactly how a generated HTML report typically gets surfaced for later download and review.

# GitHub Actions step example
- name: Upload HTML test report
  uses: actions/upload-artifact@v4
  with:
    name: karma-html-report
    path: reports/tests.html

Common Mistakes

Generating an HTML report but never actually uploading or archiving it anywhere accessible.
Relying on HTML report output as if it were machine-parseable, when JUnit XML serves that purpose instead.
Not setting outputFile to a stable, predictable path that CI upload steps can reliably reference.
Regenerating (and overwriting) the same report path across different CI jobs running in parallel.

Key Takeaways

HTML reporters produce a single, self-contained, human-readable test report file.
They complement, rather than replace, machine-readable formats like JUnit XML.
CI artifact upload steps are the standard way to make generated HTML reports accessible after a run.
groupSuites and related display options make large suites easier to scan visually.

Pro Tip

If your team runs periodic full regression suites, archive the generated HTML report as a build artifact every time, even on passing runs. Having a dated history of full reports is often more useful during a later investigation than anyone expects when first setting it up.