Wdio Timeline Reporter

5.1.4 · active · verified Tue Apr 21

Wdio Timeline Reporter is a WebdriverIO reporter that generates an aggregated HTML report for test results, providing a timeline visualization of test execution. The current stable version is 5.1.4, with active development indicated by recent minor releases. Its key differentiators include combining test summaries, detailed test runs with embedded screenshots, error stack traces, and runtime information into a single, static HTML file. It aims to streamline debugging by providing all necessary information in one place, reducing the need to switch between terminal logs and separate screenshot files. It works seamlessly with Mocha and Jasmine frameworks in WebdriverIO v5+ and later.

Common errors

```
Error: outputDir is mandatory
```
cause The required `outputDir` option was not provided in the reporter configuration within `wdio.conf.js`.

fix Add `outputDir` to your reporter options: `reporters: [['timeline', { outputDir: './my-reports' }]]`.
```
TypeError: Cannot read properties of undefined (reading 'config')
```
cause This error or similar `TypeError` can occur if `TimelineService` is not correctly imported or instantiated in the `services` array, especially for WebdriverIO v5+.

fix Ensure `TimelineService` is imported with `import { TimelineService } from 'wdio-timeline-reporter/timeline-service';` and added to services as `services: [[TimelineService]]`.
```
ERROR @wdio/local-runner: Failed launching test session: TypeError: Cannot set property 'failures' of undefined
```
cause This can indicate an issue with reporter or service initialization within the WebdriverIO v5+ runner, potentially related to an incorrect setup of `wdio-timeline-reporter`'s service.

fix Double-check that both the `timeline` reporter is listed in `reporters` and `TimelineService` is correctly added to `services` array, as specified in the usage instructions. Ensure compatible versions of `wdio-timeline-reporter` and WebdriverIO are used.

Warnings

breaking Breaking changes exist between WebdriverIO v4 and v5 regarding how custom reporters function. `wdio-timeline-reporter` v5+ is compatible with WebdriverIO v5 and later. Users on WebdriverIO v4 must use an older version of the reporter.
Fix: For WebdriverIO v5+, ensure `wdio-timeline-reporter` is version 5.x or higher. If using WebdriverIO v4, refer to the `v4` branch of the reporter's GitHub repository for compatible versions and instructions.
gotcha For WebdriverIO v5 and later, the `TimelineService` must be explicitly imported and added to the `services` array in `wdio.conf.js`. This is mandatory to combine reports and generate the HTML output, as reporters are now initialized per runner instance.
Fix: Ensure your `wdio.conf.js` includes `import { TimelineService } from 'wdio-timeline-reporter/timeline-service';` and `services: [[TimelineService]]`.
gotcha The `outputDir` reporter option is mandatory. If not provided, the reporter will fail to generate the HTML report and screenshots.
Fix: Always specify `outputDir` in the reporter configuration: `reporters: [['timeline', { outputDir: './path/to/report' }]]`.
gotcha When using the Cucumber framework, `wdio-timeline-reporter` will report every individual step as a separate test in the timeline. This can lead to a very verbose report and might not align with a scenario-based view.
Fix: Be aware of this behavior when choosing `wdio-timeline-reporter` for Cucumber projects. Consider alternative reporters if a consolidated scenario-level report is preferred. No direct fix within the reporter for this behavior.
gotcha Screenshot configuration can be done via both the `TimelineService` options and the reporter options. If `embedImages` or `screenshotStrategy` are defined in both, the reporter options usually take precedence or might lead to unexpected behavior if not consistent.
Fix: Centralize screenshot configuration in either the `TimelineService` options or the reporter options, ensuring consistency. The `embedImages` option in reporter config determines if images are base64-encoded into the HTML.

Install

npm install wdio-timeline-reporter npm
yarn add wdio-timeline-reporter yarn
pnpm add wdio-timeline-reporter pnpm

Imports

TimelineService
wrong:
```
const { TimelineService } = require('wdio-timeline-reporter');
```
correct:
```
import { TimelineService } from 'wdio-timeline-reporter/timeline-service';
```
The `TimelineService` is explicitly imported from a nested path (`/timeline-service`) rather than the root package. While CommonJS `require` is shown in the README, ESM `import` should be used in modern WebdriverIO configurations.
Reporter Configuration (string)
wrong:
```
reporters: ['WdioTimelineReporter']
```
correct:
```
reporters: [['timeline', { outputDir: './reports' }]]
```
The reporter itself is referenced by the string `'timeline'` within the `reporters` array in `wdio.conf.js`, not by a direct class import. Configuration options are passed as an object.
addContext (static method)
wrong:
```
browser.addContext('My Test', { info: 'Additional data' });
```
correct:
```
TimelineService.addContext('My Test', { info: 'Additional data' });
```
To add extra information to a test at runtime, use the static `addContext` method directly on the imported `TimelineService` class.

Quickstart

This quickstart demonstrates how to configure the `wdio-timeline-reporter` and its mandatory `TimelineService` in a `wdio.conf.js` file, including basic reporter options and how to add custom context to tests. It assumes WebdriverIO v5+ is installed.

import { TimelineService } from 'wdio-timeline-reporter/timeline-service';

exports.config = {
  runner: 'local',
  specs: [
    './test/specs/**/*.ts'
  ],
  exclude: [],
  maxInstances: 10,
  capabilities: [{
    maxInstances: 5,
    browserName: 'chrome',
    acceptInsecureCerts: true
  }],
  logLevel: 'info',
  bail: 0,
  baseUrl: 'http://localhost',
  waitforTimeout: 10000,
  connectionRetryTimeout: 120000,
  connectionRetryCount: 3,
  services: [
    [TimelineService, {
      // Optional: Configure screenshot management via TimelineService
      embedImages: true, // Embed screenshots as base64 in HTML
      screenshotStrategy: 'on:error' // Take screenshots only on test failure
    }]
  ],
  framework: 'mocha',
  reporters: [
    ['timeline', {
      outputDir: './timeline-report', // Mandatory: Directory for reports and screenshots
      fileName: 'custom-timeline-report.html', // Optional: Custom report file name
      embedImages: true // Embed images in report, overrides service setting if different
    }]
  ],
  mochaOpts: {
    ui: 'bdd',
    timeout: 60000
  },
  // Your tests go here (e.g., in ./test/specs/**/*.ts)
  // Example test content:
  // describe('My Test Suite', () => {
  //   it('should perform a successful action', async () => {
  //     await browser.url('https://webdriver.io');
  //     await expect(browser).toHaveTitleContaining('WebdriverIO');
  //   });
  //
  //   it('should add context data', async () => {
  //     await browser.url('https://example.com');
  //     TimelineService.addContext(this, { data: 'some useful info' });
  //     await expect(browser).toHaveTitle('Example Domain');
  //   });
  // });
};

view raw JSON →