jest-html-reporters: an HTML report for Jest test runs

A Jest reporter that writes a page instead of a log

jest-html-reporters is a Jest test results processor for generating a summary in HTML. The mechanism is the standard Jest reporter slot rather than a wrapper, so it runs as part of your existing test command and produces a file you open in a browser.

The output is a file called jest_html_reporters.html, created in your root folder as you run Jest from within the terminal, and it contains information about your tests. The repository homepage points at a hosted example page, and the README carries an animated demonstration of the interface.

The audience is a team running Jest on a continuous integration server. The plain terminal output of a test run is fine for a developer at a desk, and awkward for a build that finishes while nobody is watching. A single HTML file is the artifact you can attach to a build, publish, or open from a laptop ten minutes later.

The package is published to npm as jest-html-reporters, with the entry point index.js and TypeScript declarations at index.d.ts. The source is TypeScript, the repository has a src/ directory with a build/ directory for the compiled output, and the interactive page is assembled from templates/ and public/ assets. There is also a helper.ts at the root, which is the entry point for the attachment API discussed below, and a separate docs/ directory with a Simplified Chinese version of the readme.

Registering the reporter in the Jest config

The reporter is added to the reporters array in the Jest config, in this case jest.config.json, alongside the default reporter:

"jest": {
  ...,
  "reporters": [
    "default",
    "jest-html-reporters"
  ],
  ...
}

Keeping default in the list matters. Jest's default reporter is what prints to the terminal, and dropping it means you lose the console output your CI logs depend on.

Options are passed as a second element in the reporters array, as a tuple of the reporter name and an options object:

...,
"reporters": [
  "default",
  ["jest-html-reporters", {
    "publicPath": "./html-report",
    "filename": "report.html",
    "openReport": true
  }]
]

That form is what you need for anything beyond the defaults. The example sets the output directory to ./html-report, changes the file name from the default jest_html_reporters.html to report.html, and turns on openReport.

The openReport option defaults to true in development and false elsewhere, and it works through the npm package open. That default is deliberate: opening a browser window on a developer machine is convenient, and doing it on a CI server is wrong. Setting it to true in the config as the example does, in a project that also runs locally, gives you the convenience locally, and the option is where you would turn it off for a CI environment if you configure it globally.

Installing the package and adding it to devDependencies

Installation is one command, with yarn and npm both documented:

  yarn add jest-html-reporters --dev
  npm install jest-html-reporters --save-dev

It belongs in your development dependencies, since it only runs at test time and never ships in your bundle.

After installing, the two things to do are add the reporter to the Jest config and run your tests. You should end up with a jest_html_reporters.html file in your root folder, and opening it in a browser gives you the report.

The filename option has a default of jest_html_reporters.html and applies to the generated HTML. If you want a different name, or want the report in a subdirectory, set filename and publicPath together, as in the configuration example above, where publicPath is the base path and filename the name of the saved report.

The publicPath option defaults to an empty string, and it is also where the attachment images are written, so it matters more than it first appears if you use the screenshot feature described further down.

The option table and the environment variable behind every option

The options are documented in a single table, and every row carries a matching environment variable, which is the detail that makes this package usable in CI.

The names follow a pattern: publicPath with JEST_HTML_REPORTERS_PUBLIC_PATH, filename with JEST_HTML_REPORTERS_FILE_NAME, includeConsoleLog with JEST_HTML_REPORTERS_INCLUDE_CONSOLE_LOG, darkTheme with JEST_HTML_REPORTERS_DARK_THEME, failureMessageOnly with JEST_HTML_REPORTERS_FAILURE_MESSAGE_ONLY, inlineSource with JEST_HTML_REPORTERS_INLINE_SOURCE, pageTitle with JEST_HTML_REPORTERS_PAGE_TITLE, logoImgPath with JEST_HTML_REPORTERS_LOGO_IMG_PATH, hideIcon with JEST_HTML_REPORTERS_HIDE_ICON, expand with JEST_HTML_REPORTERS_EXPAND, testCommand with JEST_HTML_REPORTERS_TEST_COMMAND, openReport with JEST_HTML_REPORTERS_OPEN_REPORT, urlForTestFiles with JEST_HTML_REPORTERS_URL_FOR_TEST_FILES, customInfos with JEST_HTML_REPORTERS_CUSTOM_INFOS, enableMergeData with JEST_HTML_REPORTERS_ENABLE_MERGE_DATA, dataMergeLevel with JEST_HTML_REPORTERS_DATA_MERGE_LEVEL, and the temporary folder path with JEST_HTML_REPORTERS_TEMP_DIR_PATH.

The practical effect is that a CI job can set the options it needs without editing a committed config file, which matters when the same repository is built in several environments with different requirements.

A few of the options are worth reading closely. failureMessageOnly is a number, not a boolean: 0 always creates the report, 1 shows failure test suite messages only in the report, and 2 only creates the report when some test suites failed. includeConsoleLog defaults to false and, as the table notes, requires running Jest with verbose=false to catch all logs during the tests, so it is not a simple switch. urlForTestFiles adds an icon link to each row of the details table, with the URL built by joining that value to the relative path of the test file.

Collapsing test data and attaching screenshots

Two features carry most of the practical value.

The first is collapsible test groups. When a single test file contains many test cases, the expanded table shows a Merge Data checkbox, and checking it merges the data, with the merge level controlling how the data is combined. The option that drives this is enableMergeData, described as the default merge test data feature, with dataMergeLevel setting the merge level, defaulting to 1.

The second is attaching a screenshot to the report, through a method named addAttach, whose parameters are typed like this:

interface IAddAttachParams {
    attach: string | Buffer;
    description: string | object;
    context: any;
    bufferFormat: string;
}

The attach parameter is the image, and it can be a buffer or a string. If you pass a buffer, the package creates a directory named jest-html-reporters-attach and saves the buffer as a jpg image in it under the publicPath. If you have already saved the image, you pass its path as the attach parameter instead. The context parameter is optional and defaults to this.global.

The documented example imports the helper directly and uses Puppeteer:

const { addAttach } = require("jest-html-reporters/helper");
const puppeteer = require("puppeteer");

This is the feature that turns the report from a test list into something a non-engineer can look at, since a failing browser test can show you the screen as it was at the moment of failure.

inlineSource for a single self-contained file

The inlineSource option saves the report in a single combined HTML file, and it is listed with a link to the issue where the request was tracked. The default is false.

Why it matters is that a normal report is not one file. The generated page pulls in assets, and with attachments present it also references image files in the jest-html-reporters-attach directory under the publicPath. That is fine when the report is served from a web server or archived as a directory, and awkward when you want to attach one file to a build result or drop it in a chat message.

With inlineSource enabled, the report becomes self-contained, which is the shape most CI artifact stores and most chat clients want. The trade-off is file size, since everything is embedded in the HTML, and a run with many attached screenshots will produce a large document.

The other options that change the shape of the output are pageTitle, which sets the header and the page title and defaults to Report, hideIcon, which hides the default icon, and logoImgPath, which points at an image displayed to the right of the page title. darkTheme generates a dark theme report page. expand specifies whether all data is expanded by default. And testCommand copies a command into the report so a reader can quickly run the test file, which is handy for a shared report where the person reading it is not the person who wrote the test.

MIT licence, a quiet release line, and a plain TypeScript build

The licence is MIT, stated in the package metadata and in the LICENSE file at the repository root. MIT is permissive, with no copyleft obligation, so a company can use the reporter inside a proprietary test setup without any disclosure requirement.

The release record is the thing to note. The listed versions are v3.1.7 on 2023-12-26, v3.1.6 on 2023-12-20 and v3.1.5 on 2023-11-25, and the last push to the repository was on 2026-10-13. The package version in the metadata is 3.1.7, matching the last release, so the published artifact and the repository have been in step for a while. If you are evaluating this, plan to pin the version rather than track a moving major, because there is no sign of a v4 and the release cadence has slowed to point releases.

The build is straightforward TypeScript. The scripts compile with tsc against the build/ configuration and then run node scripts/build.js, and the same pattern backs the test script, the CI variant that forces the default reporter, and a separate script that verifies the published package files. The commit script is cz, the pull request script shells out to gh pr create, and publish.sh sits at the root. There is also a scripts/start.js for local development, and the repository carries config/, templates/, public/ and test/ directories.

For a small utility package, that is a reasonable amount of tooling, and the absence of a framework dependency in the runtime path is what keeps the install light.

Editorial conclusion

Adopt jest-html-reporters if your team runs Jest in CI and needs a report people can open in a browser, especially for end-to-end runs with screenshots attached. Do not adopt it if the console output is enough, if you need a machine-readable report, or if you want a maintained package without pinning. Verify first that the report file and any publicPath you set are reachable from wherever the report is published, that includeConsoleLog is only enabled alongside the verbose=false run it requires, and that the version you install matches the Jest major version in your project.

Frequently asked questions

Official sources

1. Hazyzh/jest-html-reporters on GitHub
2. License: MIT
3. Project website
4. README
5. Releases