How to Generate HTML Reports with WebdriverIO

To generate an HTML report with WebdriverIO, add a reporter integration to the reporters array in your WebdriverIO configuration. The documented JSON HTML workflow collects JSON results during the test run, then converts them to HTML in the onComplete hook. For a different workflow, the HTML Nice Reporter can create a master report from suite output. These are third-party integrations documented by WebdriverIO, so confirm package compatibility and option names for your installed versions before adopting a configuration. WebdriverIO configuration · JSON HTML Reporter · HTML Reporter

Choose an HTML report workflow

Pick the integration based on what the report needs to show and how your test run is structured. The reporter package controls its own output settings; WebdriverIO’s general outputDir is for runner log files and should not be assumed to configure a reporter’s report path.

Need	Workflow to consider
Generate a portable dashboard from run data	`wdio-json-html-reporter`: collect JSON and convert the output folder to HTML, either in `onComplete` or with its documented CLI.
Create one report across suites	`wdio-html-nice-reporter`: use its documented `ReportGenerator` flow to assemble a master report at completion.
Keep run history or trend context	Review JSON HTML’s optional history support and Serenity/JS HTML Reporter’s `maxHistory` and `consistencyWindow` settings.
Attach execution evidence	Consider screenshots in JSON HTML, trace artifacts with Allure, or video reporter integrations. These are optional additions, not requirements for basic HTML output.
Control report behavior beyond an integration’s options	Implement a custom reporter that inherits from `@wdio/reporter`.

See the primary docs for Serenity/JS HTML Reporter, WebdriverIO DevTools and Allure, Video Reporter, and Custom Reporter.

Generate HTML with the JSON HTML Reporter

This approach has two stages: the reporter writes JSON during the run, then a generator turns the JSON folder into an HTML file after the run completes. The package documentation shows a JSONReporter entry and an asynchronous HTMLReportGenerator call in onComplete. The example below illustrates that documented flow; verify the import and option names against the package version in your lockfile.

1. Install the integration

npm install --save-dev wdio-json-html-reporter

Keep the package version in your lockfile and check its current integration instructions alongside your WebdriverIO version. The reviewed WebdriverIO pages do not establish a universal compatibility matrix for every major release.

2. Configure collection and conversion

In your WebdriverIO configuration, register the JSON reporter and generate the HTML output in onComplete. The output paths here are example paths; keep the reporter’s JSON folder and the generator’s input folder aligned.

import { JSONReporter, HTMLReportGenerator } from 'wdio-json-html-reporter';

export const config = {
  // Keep the rest of your WebdriverIO configuration here.
  reporters: [
    [JSONReporter, {
      outputFile: './reports/json/results.json',
      screenshot: true,
    }],
  ],

  async onComplete() {
    const generator = new HTMLReportGenerator({
      outputFile: './reports/html/index.html',
    });

    await generator.convertJSONFolderToHTML('./reports/json');
  },
};

Reporter-specific configuration differs between integrations. Use the JSON HTML package’s documented configuration as the authority for the exact constructor and option shape for your installed release. Do not substitute WebdriverIO’s general outputDir for the package’s own output configuration.

3. Run WebdriverIO and open the artifact

Run your project’s normal WebdriverIO command, then open reports/html/index.html or publish that file as a CI artifact. The HTML conversion needs to finish before the process exits; awaiting it in the completion hook makes that ordering explicit.

The package also documents a CLI conversion form:

generate-html <inputFolder> <outputFile> [historyFile]

For example, once the package’s CLI is available in your project, pass the folder containing its JSON output and the destination HTML path. Check the package instructions for executable resolution and optional history-file details.

Aggregate reports across suites

Do not assume parallel workers or multiple suites will be combined automatically. The HTML Nice Reporter documentation describes that the runner invokes a reporter per suite and shows a ReportGenerator flow to create a master report in onComplete. Follow its setup and cleanup guidance, including its onPrepare flow, and ensure intermediate suite output is available to the process that creates the master report.

For sharded CI runs, decide where each shard writes results and where aggregation runs. The documentation does not define universal behavior for every CI sharding setup, so verify that your own workers produce all expected input files before generating the final report.

The HTML Nice Reporter page documents reporter settings such as output directory, filename, title, screenshot handling, browser display, collapsed tests, and screenshots after commands. Use its configuration and master-report example for exact syntax.

Add history and failure evidence when needed

Run history: JSON HTML documents optional historical execution data. Serenity/JS exposes options including maxHistory, consistencyWindow, project name, test-run ID, and module ID. Choose one history approach and define where prior run data will persist in CI. See the Serenity/JS options.
Screenshots: JSON HTML documents screenshot support. Enable it only if screenshots help diagnose failures, and account for the size and retention of the generated artifacts.
Traces and video: WebdriverIO’s DevTools documentation describes trace artifacts attaching to Allure when @wdio/allure-reporter is configured. The video reporter documentation describes integrations with Allure and HTML Nice Reporter. These add evidence collection and related setup; they are not prerequisites for an HTML report. See DevTools / Allure and Video Reporter.

Important configuration details

Reporter registration: WebdriverIO accepts reporter names or entries containing a reporter name and reporter-specific options. Follow the integration’s expected form; examples may register an imported class.
Output paths: Keep intermediate JSON and final HTML paths distinct and explicit. Create or clean directories as the integration documentation recommends.
Completion timing: If conversion happens after test execution, await the conversion from the completion hook so the runner does not finish before the artifact is written.
Parallelism: Determine whether workers write separate files and whether an aggregator is configured. A reporter entry alone does not prove that all suite data reaches one report.
CI artifacts: Configure your CI system to retain the HTML file and any evidence you need. Report generation and artifact upload are separate steps.
Custom reporters: If package options cannot express the required behavior, WebdriverIO documents extending @wdio/reporter to implement a custom reporter.

The WebdriverIO configuration reference also documents reporter synchronization settings. Its general output directory stores runner log files; use reporter-specific settings for report output.

Or skip the browser setup

If your goal is a screenshot artifact alongside a test report, ScreenshotNeo can capture a page with one GET request. It is a website screenshot API and MCP server for developers. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo is separate from WebdriverIO’s test report: use it when you need a page screenshot, not as a replacement for structured test results. Sign up for 1,000 free screenshots a month, with no card.

Troubleshooting

Symptom	Likely cause	What to check
No HTML file appears	The conversion hook did not run, the JSON input folder is wrong, or generation failed.	Confirm the run reached `onComplete`, inspect the configured JSON output, and await the generator call. Check the package’s current option names.
HTML exists but has no results	The converter is reading a different directory than the reporter wrote to, or the expected intermediate files are absent.	Compare the reporter output path with the folder passed to `convertJSONFolderToHTML`; inspect the JSON artifacts before conversion.
Some suites are missing	Parallel or per-suite outputs were not gathered by the master-report step.	Follow the selected reporter’s aggregation setup. Verify all worker outputs are available where and when the generator runs.
The process exits before report generation completes	Asynchronous conversion was started without being awaited.	Return or await the conversion promise from the completion hook.
Configuration fails after a package upgrade	An import, option, or compatibility assumption differs from the installed package version.	Use the package documentation and lockfile to align the import and configuration with the version actually installed. The WebdriverIO docs do not provide a universal compatibility matrix.
CI run succeeds but artifact is unavailable	Report generation succeeded locally in the job, but artifact retention or upload is not configured for that path.	Check the final output path and configure the CI artifact step to retain it.
History is empty or trends reset	Historical data was not supplied or persisted between runs, or history settings differ.	Review the selected package’s history configuration and preserve its history input across runs if trends are required.

Performance, reliability, and cost considerations

HTML generation adds work after the browser tests finish, and screenshots, traces, or video add artifact storage. The cited reporter pages do not provide comparable performance benchmarks, so measure report-generation time and artifact size in your own suite if they affect CI duration or retention.

For reliability, keep report generation in the runner lifecycle, await asynchronous conversion, and make intermediate and final paths explicit. In parallel or sharded runs, treat aggregation as a separate requirement and verify inputs before publishing the master report. These reporter packages are software integrations; check their current maintenance, release metadata, and compatibility with your WebdriverIO version.

WebdriverIO’s documented reporters and reporting integrations do not establish a universal report-generation price. Budget for the CI execution and artifact storage choices your team uses. If you also need website screenshots, ScreenshotNeo’s published plans are Free: 1,000 shots per month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; and Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. See ScreenshotNeo for the product details.

FAQ

Does WebdriverIO include an HTML reporter by default?

The documented JSON HTML and HTML Nice reporters are third-party integrations. Add and configure the integration that fits your output needs.

Can I generate the report without putting conversion in a hook?

The JSON HTML package documents a CLI conversion command as well as conversion from the completion hook. Use the CLI when it fits your build pipeline, and pass the correct input folder and output file.

Will one HTML report include every parallel suite automatically?

Do not assume so. Use the selected reporter’s documented aggregation flow and verify it receives each suite’s output.

Can I make a custom HTML report?

WebdriverIO documents custom reporters that inherit from @wdio/reporter. That route is useful when an integration’s output and options do not meet your requirements.