Workflow:Webdriverio Webdriverio Custom Plugin Development
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Plugin_Development, Extensibility |
| Last Updated | 2026-02-12 01:30 GMT |
Overview
End-to-end process for extending WebdriverIO by creating custom services and reporters that hook into the test lifecycle.
Description
This workflow demonstrates how to build custom WebdriverIO plugins: services that execute custom logic at test lifecycle points (before/after sessions, tests, commands), and reporters that process and output test results in custom formats. Services are the primary extension mechanism for integrating with external tools, managing test infrastructure, capturing diagnostics, or adding custom browser commands. Reporters transform test events into output formats for CI dashboards, analytics platforms, or custom reporting needs. Both follow a class-based pattern with well-defined hook methods.
Usage
Execute this workflow when the built-in services and reporters do not meet your needs, such as when integrating with a proprietary test management system, capturing custom performance metrics, managing custom test infrastructure, or generating reports in a specific format required by your organization.
Execution Steps
Step 1: Define Plugin Requirements
Determine whether you need a service, a reporter, or both. Services hook into the test lifecycle to perform actions (setup environments, capture data, modify browser behavior). Reporters receive test events and transform them into output (files, API calls, dashboards).
Key considerations:
- Services have two components: a Launcher (runs in the main process once) and a Service (runs in each worker process)
- Reporters extend the base WDIOReporter class and receive test event callbacks
- A single package can export both a service and a reporter
- Determine which lifecycle hooks your plugin needs
Step 2: Create Custom Service
Implement a service class with lifecycle hook methods. The service receives the WDIO configuration in its constructor and can implement any combination of hooks. Common hooks include onPrepare (before all tests), before (before each worker's tests), beforeTest (before each test), afterTest (after each test), after (after each worker), and onComplete (after all tests).
Key considerations:
- onPrepare(config, capabilities) runs once in the main process before workers start
- onWorkerStart(cid, caps, specs) runs when each worker process starts
- before(caps, specs, browser) runs before each worker's test execution begins
- beforeTest(test, context) runs before each test case
- beforeCommand(commandName, args) runs before each WebdriverIO command
- afterCommand(commandName, args, result, error) runs after each WebdriverIO command
- afterTest(test, context, result) runs after each test case
- after(result, caps, specs) runs after all tests in a worker complete
- onComplete(exitCode, config, capabilities, results) runs once in the main process after all workers finish
Step 3: Create Custom Reporter
Extend the WDIOReporter base class and implement event handler methods. The reporter receives real-time test events and can write output using the this.write() method (for file output) or custom logic (for API calls, database storage, etc.).
Key considerations:
- Extend WDIOReporter from @wdio/reporter
- Call super(options) in the constructor to initialize the base class
- onRunnerStart(runner) fires when a test worker begins
- onSuiteStart(suite) fires when a test suite begins
- onTestStart(test) fires before each test
- onTestPass(test) fires when a test passes
- onTestFail(test) fires when a test fails
- onTestSkip(test) fires when a test is skipped
- onSuiteEnd(suite) fires when a suite completes
- onRunnerEnd(runner) fires when a worker finishes
- Use this.write(data) to write to the output stream
Step 4: Register Plugin in Configuration
Add the custom service or reporter to the wdio.conf.ts configuration file. Services are added to the services array and reporters to the reporters array. Plugins can be referenced by module path or as inline class references.
Key considerations:
- Reference by path: services: [['./my.custom.service.js', { option: 'value' }]]
- Reference by class: services: [[MyService, { option: 'value' }]]
- Reporter with options: reporters: [['./my.custom.reporter.js', { outputDir: './reports' }]]
- Options are passed as the second element of the tuple array
Step 5: Test and Package
Test the plugin by running it with a sample test suite. Verify that all lifecycle hooks fire correctly, output is generated as expected, and the plugin handles errors gracefully. For distribution, package the plugin as an npm module following the wdio-*-service or wdio-*-reporter naming convention.
Key considerations:
- Test with multiple frameworks (Mocha, Jasmine, Cucumber) if the plugin should work with all
- Handle errors within hooks to avoid crashing the test runner
- Follow the naming convention: wdio-{name}-service or wdio-{name}-reporter
- Export both the service/reporter class and optionally a launcher class
- Publish to npm for community use or keep internal for organization-specific needs