Principle:Webdriverio Webdriverio Custom Reporter Development

Overview

A plugin architecture for creating custom test result formatters by extending a base reporter class.

Description

Custom Reporter Development enables creating purpose-specific test result output by extending the WDIOReporter base class. Reporters receive test lifecycle events (runner start/end, suite start/end, test pass/fail/skip) and produce formatted output. This supports use cases like custom dashboards, specialized CI formats, database logging, and team notification integrations.

Unlike services (which hook into the test runner lifecycle), reporters are specifically designed for output generation. They receive structured event data (stats objects with timing, counts, and hierarchy information) and transform it into a desired output format. The base class handles:

• Event subscription -- Automatically listens for all test lifecycle events via EventEmitter
• Output stream management -- Manages file or stdout output via configurable WriteStreams
• Statistics tracking -- Maintains counts of suites, tests, hooks, passes, failures, skips, and pending tests
• Hierarchical state -- Tracks the current suite stack, enabling reporters to understand test nesting

The reporter architecture supports two output modes:

• File output -- When outputDir or logFile is specified, the reporter writes to a file. If the file ends up empty (no content written), the reporter automatically cleans it up.
• Stream output -- When stdout: true or a custom writeStream is provided, the reporter writes to that stream, enabling real-time console output or piping to other tools.

Reporters receive rich event data through Stats objects:

• RunnerStats -- Contains session ID, capabilities, specs, config, and overall timing
• SuiteStats -- Contains suite title, file, parent reference, and child tests/hooks
• TestStats -- Contains test title, full title, duration, state (passed/failed/skipped), errors, and command output
• HookStats -- Contains hook title, duration, and error information

Usage

Use Custom Reporter Development when built-in reporters (spec, junit, allure) do not meet your needs. Create a class extending WDIOReporter, override event handler methods, and use this.write() for output. Register in the reporters array in wdio.conf.ts.

Creating a basic custom reporter:

// my.custom.reporter.js
import WDIOReporter from '@wdio/reporter'

export default class CustomReporter extends WDIOReporter {
    constructor(options) {
        super(options)
        console.log('Reporter initialized with options:', options)
    }

    onRunnerStart(runnerStats) {
        this.write(`Test run started: ${runnerStats.specs.join(', ')}\n`)
    }

    onSuiteStart(suiteStats) {
        this.write(`  Suite: ${suiteStats.title}\n`)
    }

    onTestPass(testStats) {
        this.write(`    PASS: ${testStats.title} (${testStats.duration}ms)\n`)
    }

    onTestFail(testStats) {
        this.write(`    FAIL: ${testStats.title}\n`)
        this.write(`      Error: ${testStats.errors?.[0]?.message}\n`)
    }

    onTestSkip(testStats) {
        this.write(`    SKIP: ${testStats.title}\n`)
    }

    onRunnerEnd(runnerStats) {
        this.write(`\nResults: ${this.counts.passes} passed, `)
        this.write(`${this.counts.failures} failed, `)
        this.write(`${this.counts.skipping} skipped\n`)
    }
}

Registering the reporter:

// wdio.conf.ts
import CustomReporter from './my.custom.reporter.js'

export const config: WebdriverIO.Config = {
    reporters: [
        [CustomReporter, {
            outputDir: './reports',
            someCustomOption: true
        }]
    ]
}

When to use:

• Generating custom output formats for internal dashboards or CI systems
• Logging test results to databases or external APIs
• Sending notifications (Slack, email) based on test outcomes
• Creating specialized compliance or audit reports

When not to use:

• When a built-in reporter (spec, dot, junit, allure) meets your needs
• When you only need to react to test lifecycle events without producing output (use a service instead)

Theoretical Basis

Reporters implement the Observer/Listener pattern. The WDIOReporter base class extends Node.js EventEmitter and subscribes to test lifecycle events on construction. Subclasses override event handler methods (onRunnerStart, onTestPass, onTestFail, etc.) to produce custom output.

The this.write() method handles output stream management, supporting both file and stdout output. This abstraction means reporters do not need to manage file handles, stream flushing, or output destination logic.

The event flow follows a strict ordering:

Event	Handler	Data	When
runner:start	onRunnerStart	RunnerStats	Worker process begins
suite:start	onSuiteStart	SuiteStats	Each describe/suite block begins
hook:start	onHookStart	HookStats	Before/after hooks run
hook:end	onHookEnd	HookStats	Before/after hooks complete
test:start	onTestStart	TestStats	Each test begins
test:pass	onTestPass	TestStats	Test passes
test:fail	onTestFail	TestStats	Test fails
test:retry	onTestRetry	TestStats	Test is retried
test:pending	onTestSkip	TestStats	Test is skipped
test:end	onTestEnd	TestStats	Test completes (any outcome)
suite:end	onSuiteEnd	SuiteStats	Suite completes
runner:end	onRunnerEnd	RunnerStats	Worker process completes

The Template Method pattern is also at play: the base class defines the algorithm (subscribe to events, create stats objects, call handlers) and subclasses provide specific implementations for each handler.

Reporters also receive command events (client:beforeCommand, client:afterCommand) and assertion events (client:beforeAssertion, client:afterAssertion), enabling detailed logging of WebDriver commands executed during tests.

Related Pages

Implementation:Webdriverio_Webdriverio_WDIOReporter_Base_Class

• implemented_by Implementation:Webdriverio_Webdriverio_WDIOReporter_Base_Class