Skip to main content

Support for WebdriverIO 8

ยท 6 min read

WebdriverIO Roboter

Serenity/JS started to support WebdriverIO in version 2.30.0.

In version 3.0.0, Serenity/JS brought you @serenity-js/web - a portable abstraction layer that lets you run the exact same web scenario with WebdriverIO, Playwright, and even Protractor!

Now, we're taking things further with Serenity/JS 3.2.0 introducing support for the latest and greatest WebdriverIO 8! ๐Ÿฅณ

In this article, and in less than 5 minutes, you'll learn how to integrate Serenity/JS with your WebdriverIO test suite, enable Serenity BDD reports, and start using the Screenplay Pattern!

About Serenity/JSโ€‹

Serenity/JS is an open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative, and easier to scale.

For WebdriverIO test suites, Serenity/JS offers:

Serenity BDD Report Example

Installing Serenity/JSโ€‹

To add Serenity/JS to an existing WebdriverIO project, install the following Serenity/JS modules from NPM:

npm install @serenity-js/{core,web,webdriverio,assertions,console-reporter,serenity-bdd} --save-dev

Learn more about Serenity/JS modules:

Configuring Serenity/JS and WebdriverIOโ€‹

To enable integration with Serenity/JS, configure WebdriverIO as follows:

import { WebdriverIOConfig } from '@serenity-js/webdriverio';

export const config: WebdriverIOConfig = {

// Tell WebdriverIO to use Serenity/JS framework
framework: '@serenity-js/webdriverio',

// Serenity/JS configuration
serenity: {
// Configure Serenity/JS to use the appropriate adapter
// for your test runner
runner: 'cucumber', // or 'mocha', or 'jasmine'

// Register Serenity/JS reporting services, a.k.a. the "stage crew"
crew: [
// Optional, print test execution results to standard output

// Optional, produce Serenity BDD reports
// and living documentation (HTML)
[ '@serenity-js/core:ArtifactArchiver', {
outputDirectory: 'target/site/serenity'
} ],

// Optional, automatically capture screenshots
// upon interaction failure
[ '@serenity-js/web:Photographer', {
strategy: 'TakePhotosOfFailures'
} ],

// Configure your Cucumber runner
cucumberOpts: {
// see Cucumber configuration options below

// ... or Jasmine runner
jasmineOpts: {
// see Jasmine configuration options below

// ... or Mocha runner
mochaOpts: {
// see Mocha configuration options below

runner: 'local',

// Any other WebdriverIO configuration

Learn more about:

Producing Serenity BDD reports and living documentationโ€‹

Serenity BDD reports and living documentation are generated by Serenity BDD CLI, a Java program downloaded and managed by the @serenity-js/serenity-bdd module.

To produce Serenity BDD reports, your test suite must:

  • download the Serenity BDD CLI, by calling serenity-bdd update which caches the CLI jar locally
  • produce intermediate Serenity BDD .json reports, by registering SerenityBDDReporter as per the configuration instructions
  • invoke the Serenity BDD CLI when you want to produce the report, by calling serenity-bdd run

The pattern used by all the Serenity/JS Project Templates relies on using:

  • a postinstall NPM script to download the Serenity BDD CLI
  • npm-failsafe to run the reporting process even if the test suite itself has failed (which is precisely when you need test reports the most...).
  • rimraf as a convenience method to remove any test reports left over from the previous run
"scripts": {
"postinstall": "serenity-bdd update",
"clean": "rimraf target",
"test": "failsafe clean test:execute test:report",
"test:execute": "wdio wdio.conf.ts",
"test:report": "serenity-bdd run"

To learn more about the SerenityBDDReporter, please consult:

Using Serenity/JS Screenplay Pattern APIsโ€‹

The Screenplay Pattern is an innovative, user-centred approach to writing high-quality automated acceptance tests. It steers you towards an effective use of layers of abstraction, helps your test scenarios capture the business vernacular of your domain, and encourages good testing and software engineering habits on your team.

By default, when you register @serenity-js/webdriverio as your WebdriverIO framework, Serenity/JS configures a default cast of actors, where every actor can:

This should be enough to help you get started with introducing test scenarios that follow the Screenplay Pattern even to an existing test suite, for example:

import { actorCalled } from '@serenity-js/core'
import { Navigate, Page } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

describe('My awesome website', () => {
it('can have test scenarios that follow the Screenplay Pattern', async () => {
await actorCalled('Alice').attemptsTo(``),
equals(`WebdriverIO ยท Next-gen browser and mobile automation test framework for Node.js | WebdriverIO`)

it('can have non-Screenplay scenarios too', async () => {
await browser.url('')
await expect(browser)
.toHaveTitle('WebdriverIO ยท Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')

To learn more about the Screenplay Pattern, check out:

Next stepsโ€‹

Well done, your WebdriverIO test suite is now integrated with Serenity/JS! ๐ŸŽ‰๐ŸŽ‰๐ŸŽ‰

To take things further, check out:

Remember, new features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star โญ๏ธ Serenity/JS on GitHub to help others discover the framework!

Follow Serenity/JS on LinkedIn Watch Serenity/JS on YouTube Join Serenity/JS Community Chat GitHub stars