WDIO JSON HTML REPORTER

This is a custom WebDriverIO reporter that generates detailed JSON reports during test execution and provides a portable HTML report generator to visualize your test results. It logs timestamps, execution metadata, and can capture screenshots on demand. The package follows the WebDriverIO convention for reporters and is published as an npm package under the name wdio-json-html-reporter.

⚡️ Dual Compatibility: CommonJS and ESM

This package works in both CommonJS (require) and ES Module (import) projects.

For CommonJS (require):

const { JSONReporter, HTMLReportGenerator } = require('wdio-json-html-reporter');

For ESM (import):

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

Table of Contents

• Overview
• Features
• Installation
  • 1. Install the package
  • 2. Verify installation
  • 3. Update WebDriverIO Configuration
  • 4. Run Your Tests
• CLI Usage
• History Option and Aggregated History Generation
• Screenshots

Overview

WDIO JSON HTML REPORTER provides two main components:

• JSONReporter: A custom reporter that extends the WebDriverIO reporter interface to collect test events and generate a JSON file with metadata, test results, and (optionally) screenshots.
• HTMLReportGenerator: A utility to convert multiple JSON report files into a comprehensive HTML report with interactive charts, filtering, and export functionality. In addition, the report generator now supports an optional history file to display historical execution data if available. When no history data is provided, the report omits the historical section and shows only the Unique Errors.

These tools help you gain clear insights into your test runs, which is essential for debugging and continuous integration.

Features

• JSON Reporting: Detailed report with timestamps, suite names, test results, errors, and optional screenshots.
• HTML Reporting: Converts JSON reports into a portable HTML report with a dashboard, charts, detailed test report, and filtering capabilities.
• Export to Excel: The detailed test report can be exported to an Excel file.
• Screenshot Support: Capture screenshots for failed tests (or all tests) based on your configuration.
• Execution Metadata: Logs browser information, execution start/end times, and overall duration.
• Historical Execution (Optional): Provide a history JSON file to include historical execution data by suite. If no historical data is provided, the report will automatically hide this section and display only the Unique Errors.
• Aggregated History Generation: The JSON reporter now includes an aggregated history generation feature. Using the static method JSONReporter.generateAggregateHistory({ reportPaths, historyPath, maxHistory }), you can automatically scan all JSON report files (matching the pattern test-report-*.json) in your report directory, aggregate test results, and compute defect comparisons based on historical data. The aggregated history record is then appended to your history file and can be used by the HTML report generator to visualize trends over time.

Installation

To install the wdio-json-html-reporter package, follow these steps:

1. Install the package

Run the following command to install the package as a development dependency:

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

2. Verify installation

Ensure that the package has been installed correctly by running:

npm list wdio-json-html-reporter

If installed correctly, you should see an output similar to:

[email protected]

3. Update WebDriverIO Configuration

Modify your wdio.conf.js or wdio.conf.ts file to include the custom reporter:

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

export const config = {
  reporters: [
    [JSONReporter, { outputFile: './reports/test-results.json', screenshotOption: 'OnFailure' }],  // Options: "No", "OnFailure", "Full"
  ],
  onComplete: async function() {
    const outputFilePath = './reports/test-report.html';
    const jsonFolder = './reports'; // Directory where JSON reports are saved

    // If you want to include historical data, specify the history JSON file path here.
    const historyFile = './reports/history.json'; // Optional

    // Optionally, generate aggregated history data before generating the HTML report.
    // JSONReporter.generateAggregateHistory({ reportPaths: jsonFolder, historyPath: historyFile });

    const reportGenerator = new HTMLReportGenerator(outputFilePath, historyFile);
    await reportGenerator.convertJSONFolderToHTML(jsonFolder);
  }
};

4. Run Your Tests

Execute your WebDriverIO test suite:

npx wdio run wdio.conf.js

CLI Usage

In addition to integrating with WebDriverIO, you can run the HTML report generator directly from the command line using the built-in CLI.

Usage:

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

For example, if you have your JSON files in a folder named test/reports/json-reports and want to generate an HTML report named test/reports/report.html, you can run:

npx wdio-json-html-reporter generate-html test/reports/json-reports test/reports/report.html

If you also have a history file (e.g., test/reports/history.json), include it as an optional fourth parameter:

npx wdio-json-html-reporter generate-html test/reports/json-reports test/reports/report.html test/reports/history.json

Note:
The CLI functionality is triggered only when you pass the generate-html command as the first parameter. When running via WebDriverIO (e.g., with wdio run wdio.conf.js), the CLI logic is bypassed.

History Option and Aggregated History Generation

The HTML report generator now supports a history option. This allows you to provide a JSON file containing historical execution data that is merged into the report under the "Historical Execution by Suite" section. If the history file is provided and contains valid data, the report will display historical trends along with interactive charts and an accordion for each suite. If no history file is passed or if the file does not contain any suite data, the report will automatically hide the historical section and display only the Unique Errors overview.

In addition, the JSON reporter now includes an aggregated history generation feature. With the static method JSONReporter.generateAggregateHistory({ reportPaths, historyPath, maxHistory }), you can automatically scan all JSON report files (matching the pattern test-report-*.json) in your report directory, aggregate test results (summing test counts and merging suite data), and compute defect comparisons by comparing with the last aggregated record. The newly generated history record is then appended to the specified history file. This aggregated history data can subsequently be used by the HTML report generator to provide historical execution insights over multiple test runs.

Screenshots

Dashboard

Test Results

Screenshots

Filters

Excel Export