Skip to main content

WebdriverIO

WebdriverIO is a versatile framework for automating tests of modern web and mobile applications. WebdriverIO leverages the power of the WebDriver and WebDriver-BiDi protocols, developed and supported by all major browser vendors and thus guarantees a true cross-browser testing experience.

Serenity/JS revolutionises automated testing by enabling your team to write expressive, maintainable tests that align with your unique domain. Seamlessly integrating with WebdriverIO and test runners like Mocha, Cucumber, and Jasmine, Serenity/JS also offers advanced reporting that provides clear insights into test results, helping both technical teams and business stakeholders understand the quality of the system under test.

Benefits of integrating Playwright Test with Serenity/JS:

In this guide, you will learn how to:

  • Set up a new Serenity/JS + WebdriverIO project
  • Add Serenity/JS integration and reporting modules to new or existing WebdriverIO projects.
  • Implement WebdriverIO Test scenarios using Serenity/JS Screenplay Pattern APIs and the Serenity/JS WebdriverIO module.
Serenity/JS HTML Report — interactive dashboard with trend history, flaky test detection, and execution evidence (source)

Quick start 🚀​

To start testing immediately, consider using:

To see Serenity/JS reporting in action, explore the live reports generated by the Serenity/JS + WebdriverIO Project Templates:

FrameworkProject TemplateLive Report
Serenity/JS + Cucumber + WebdriverIOProject TemplateLive Report
Serenity/JS + Mocha + WebdriverIOProject TemplateLive Report
Serenity/JS + Jasmine + WebdriverIOProject TemplateLive Report

Installation​

To use Serenity/JS with WebdriverIO Test, follow the Serenity/JS installation guide to set up your development environment and core runtime dependencies. Then, create a new WebdriverIO project or add Serenity/JS integration and reporting modules to an existing project.

Initialising a WebdriverIO project​

To use the WebdriverIO CLI wizard to create a new project, run the following command in your computer terminal:

npm init wdio ./my-project

To create a Serenity/JS project, select the following options:

  • Type of testing: E2E Testing
  • Automation backend: any - Serenity/JS supports both local and remote WebdriverIO test runners; select local to keep it simple
  • Environment: web
  • Browser: any - Serenity/JS supports all browsers supported by WebdriverIO; selecting Chrome is a good starting point
  • Framework: Jasmine with Serenity/JS, Mocha with Serenity/JS, or Cucumber with Serenity/JS
  • Compiler: any - Serenity/JS supports both TypeScript and JavaScript; we recommend TypeScript for better tooling support
  • Generate test files: yes, if you'd like Serenity/JS to give you a starting point for your test scenarios
  • Test file location: accept the defaults unless you'd like to store your code in a different directory
  • Test reporter: any, Serenity/JS configures the project to use Serenity/JS reporting services, and you can add native WebdriverIO reporters too if needed
  • Plugins/add-ons/services: none; Serenity/JS doesn't require any additional plugins to work with WebdriverIO
TypeScript or JavaScript?

Using TypeScript improves code completion support in JetBrains IDEs and Visual Studio Code, reducing common coding errors.

For a step-by-step demonstration of creating a new project using the WebdriverIO CLI wizard, check out the below video:

Generating a new Serenity/JS project using the WebdriverIO configuration wizard

Using Serenity/JS Project Templates​

Serenity/JS Project Templates combine the most popular configurations of Serenity/JS modules, integration, and test tools, and include a handful of test scenarios to help you get started. All the official Serenity/JS Project Templates are available on GitHub, complete with GitHub Actions configuration, VisualStudio Code settings, and configured to publish test reports to GitHub Pages.

You can use them as a reference implementation or as a starting point for your project.

To create a new project from a Serenity/JS Project Template, click on the "Generate new project" link on the Serenity/JS Project Templates page, or click on the "Use this template" button on the template's GitHub repository page.

Learn more:

Adding Serenity/JS to an existing project​

To add Serenity/JS to an existing WebdriverIO project, you'll need to install the required Serenity/JS modules and configure the WebdriverIO test runner to use Serenity/JS framework and reporting services.

Compatibility​

Serenity/JS is compatible with:

If your existing project dependencies are older than the above, you'll need to update them first to ensure compatibility. For more information on compatibility with external tools, consult the Serenity/JS compatibility matrix.

Installing Serenity/JS core and reporting modules​

To add Serenity/JS to a WebdriverIO project, install the following modules:

npm install --save-dev @serenity-js/core @serenity-js/console-reporter @serenity-js/webdriverio @serenity-js/rest @serenity-js/web @serenity-js/html-reporter

This command installs:

Installing Serenity/JS test runner adapter​

WebdriverIO offers a local runner that uses Jasmine, Mocha, or Cucumber test runners to run your test scenarios. Depending on the test runner you use, you'll need the appropriate Serenity/JS test runner adapter.

Serenity/JS with Cucumber​

To use Serenity/JS and WebdriverIO with Cucumber.js, install the @serenity-js/cucumber adapter module:

npm install --save-dev @serenity-js/cucumber

Please note that Serenity/JS WebdriverIO / Cucumber integration supports both Serenity/JS reporting services and native Cucumber.js reporters.

Serenity/JS with Jasmine​

To use Serenity/JS and WebdriverIO with Jasmine, install the @serenity-js/jasmine adapter module:

npm install --save-dev @serenity-js/jasmine
Serenity/JS with Mocha​

To use Serenity/JS and WebdriverIO with Mocha, install the @serenity-js/mocha adapter module:

npm install --save-dev @serenity-js/mocha

Configuration​

Serenity/JS uses the standard WebdriverIO wdio.conf.ts configuration file, with an additional property called serenity for specifying Serenity/JS configuration.

To integrate WebdriverIO with Serenity/JS, ensure that your wdio.conf.ts file:

  • sets the framework option to @serenity-js/webdriverio (or @serenity-js/webdriverio-8 for WebdriverIO 8),
  • configures Serenity/JS reporting services under the serenity.crew option,
  • optionally, sets the serenity.runner option to mocha, jasmine, or cucumber to match your preferred test runner.

This section provides a step-by-step guide to the complete configuration setup.

Integrating Serenity/JS reporting​

Serenity/JS offers automatic screenshot capture for test scenarios using the Screenplay Pattern. This is handled by the Photographer service, which takes screenshots based on interactions and assertion failures performed by the Serenity/JS actors.

To integrate Serenity/JS reporting and enable automatic screenshot capture, modify the wdio.conf.ts file as follows:

wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIOConfig = {
    // Serenity/JS configuration
    framework: '@serenity-js/webdriverio',
    serenity: {
        runner: 'cucumber',
        crew: [
            // Optional, print test execution results to standard output
            '@serenity-js/console-reporter',

            // Optional, produce Serenity/JS HTML reports
            // with trend history and flaky test detection
            [ '@serenity-js/html-reporter', {
              specDirectory: './features'
            } ],

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

    specs: [
        './features/**/*.feature'
    ],

    cucumberOpts: {
        require: [
            './features/support/*.ts',
            './features/step-definitions/*.ts'
        ],
        // <string> (name) specify the profile to use
        profile: '',
        // <boolean> fail if there are any undefined or pending steps
        strict: false,
        // <string[] | string> (expression) only execute the features or scenarios with tags matching the expression
        tags: [],
        // <number> timeout for step definitions
        timeout: 60_000,
    },
};

This configuration enables the @serenity-js/webdriverio test runner adapter, which in turn configures the "stage crew" of Serenity/JS reporting services:

  • Console reporter - Displays test results in the terminal.
  • HTML Reporter - Produces a self-contained HTML report with trend history, flaky test detection, and an interactive dashboard.
  • Photographer - Automatically captures screenshots of the browser upon interactions or assertion failures when configured with TakePhotosOfInteractions or TakePhotosOfFailures, respectively.

Note that the above configuration assumes the following directory structure of your project:

  • ./test/specs or ./features - stores your test scenarios and is the top-most directory of your requirements hierarchy.

If you'd like to use a different location for your tests, adjust the specDirectory setting accordingly.

Learn more about the configuration options for your test runner:

Test RunnerConfiguration OptionsComplete wdio.conf.ts
CucumberSerenity/JS Cucumber configuration optionsCucumber Protractor Template config
JasmineSerenity/JS Jasmine configuration optionsJasmine Protractor Template config
MochaSerenity/JS Mocha configuration optionsMocha Protractor Template config

Using WebdriverIO 9 configuration​

To use the new WebdriverIO 9 configuration types, combine them with the WithSerenityConfig interface instead of using the default WebdriverIOConfig:

wdio.conf.ts
import { WithSerenityConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIO.Config & WithSerenityConfig = {
    // ... Serenity/JS configuration
}

Writing test scenarios​

Serenity/JS is designed to integrate seamlessly with your existing WebdriverIO codebase, even if you are not using the Screenplay Pattern yet. Additionally, the framework enables you to mix Screenplay and non-Screenplay scenarios within the same codebase, helping your team gradually adopt the pattern where appropriate.

In this section, you will learn how to write test scenarios using WebdriverIO and Serenity/JS APIs and how to leverage actors to structure your test interactions.

Using the Screenplay Pattern APIs​

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

To use the Screenplay Pattern APIs, import the relevant interactions and questions from the appropriate modules, and instruct your actors to perform them using the actor.attemptsTo method.

The most commonly used Screenplay Pattern APIs come from the following modules:

Using Serenity/JS actors​

A test scenario following the Screenplay Pattern models workflows of one or multiple actors representing people and external systems interacting with the system under test.

When you register @serenity-js/webdriverio as your WebdriverIO framework, Serenity/JS automatically configures a default cast of actors where every actor, where every actor has the abilities to:

To do so, Serenity/JS equips your actors with abilities to:

Overriding abilities

An actor can only have one instance of each ability type at a time. Therefore, providing a new instance of the same type via the actor.whoCan method overrides any existing ability of that type

To use an actor in your test scenario, refer to it using the actorCalled or actorInTheSpotlight functions and they'll automatically use the configured cast of actors to create or retrieve the actor you need.

test/specs/example.spec.ts
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page } from '@serenity-js/web'
import { Ensure, includes } from '@serenity-js/assertions'

describe('Example', () => {

    it('can have test scenarios that follow the Screenplay Pattern', async () => {
        await actorCalled('Alice').attemptsTo(
            Navigate.to(`https://webdriver.io`),
            Ensure.that(
                Page.current().title(),
                includes(`Next-gen browser and mobile automation test framework for Node.js`)
            ),
        )
    })

    it('can have non-Screenplay scenarios too', async () => {
        await browser.url('https://webdriver.io')
        await expect(browser)
            .toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    })
})

With Serenity/JS, you can also mix Screenplay and non-Screenplay scenarios in the same test suite and even in the same spec file. This enables you to introduce test scenarios that follow the Screenplay Pattern even to an existing test suite that doesn't use the Screenplay Pattern yet.

To learn more about the Screenplay Pattern and using Serenity/JS actors, check out:

Replacing the default actors​

If you need to replace the default cast of actors, you can do so by providing a custom implementation via serenity.actors configuration option in your wdio.conf.ts.

For example, you might want to introduce an actor called Adam, the test data admin, who can make HTTP requests to the admin API, but doesn't need to use the browsers. Conversely, you might want your other actors to use the browser but not the admin API.

test/serenity/MyActors.ts
import { Actor, Cast, TakeNotes } from '@serenity-js/core'
import { CallAnApi } from '@serenity-js/rest'
import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio'

export class MyActors implements Cast {

    // Inject custom parameters via constructor
    constructor(private readonly adminApiUrl: string) {
    }

    prepare(actor: Actor): Actor {
        // You can assign abilities based on actor name, env variables, and so on
        switch (actor.name) {
            case 'Adam':
                return actor.whoCan(
                    CallAnApi.at(this.adminApiUrl)
                )

            default:
                return actor.whoCan(
                    BrowseTheWebWithWebdriverIO.using(global.browser as WebdriverIO.Browser),
                    TakeNotes.usingAnEmptyNotepad(),
                )
        }
    }
}
No browser in the configuration file

WebdriverIO doesn't allow you to use the browser global variable in wdio.conf.ts. That's why you need to create a custom implementation of Cast and only refer to browser in Cast.prepare method.

Next, modify your WebdriverIO configuration file to provide your custom MyActors implementation:

wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'
import { MyActors } from './test/serenity/MyActors'

export const config: WebdriverIOConfig = {
    framework: '@serenity-js/webdriverio',
    serenity: {
        actors: new MyActors('https://admin-api.example.org'),
        crew: [
            '@serenity-js/console-reporter',
            ['@serenity-js/html-reporter', { specDirectory: './test/specs' }],
        ],
    },
}

Reporting​

Serenity/JS offers two reporting options for WebdriverIO projects:

  • Serenity/JS HTML Reporter — self-contained report with trend history, flaky test detection, and an interactive dashboard. No Java required.
  • Serenity BDD Reporter — multi-page HTML reports with narrative documentation. Requires Java.

Serenity/JS HTML Reporter​

The HTML Reporter is the recommended option for most teams. It produces a report automatically at the end of each test run — no separate generation step needed.

wdio.conf.ts
import type { WebdriverIOConfig } from '@serenity-js/webdriverio';

export const config: WebdriverIOConfig = {
    framework: '@serenity-js/webdriverio',

    serenity: {
        runner: 'mocha',
        crew: [
            '@serenity-js/console-reporter',
            ['@serenity-js/html-reporter', {
                specDirectory: './test/specs',   // root of your specs directory
            }],
        ],
    },

    specs: ['./test/specs/**/*.spec.ts'],
};

After running npm test, open reports/serenity-js/index.html in your browser, or serve it locally:

npx @serenity-js/html-reporter serve --open
Serenity/JS HTML Report — Dashboard with trend chart and KPI cards (source)

→ Learn more: HTML Reporter guide | CI integration

Serenity BDD Reporter​

If your team already uses Serenity BDD or prefers its multi-page report format, you can use the Serenity BDD Reporter instead of (or alongside) the HTML Reporter.

Serenity BDD reports are generated by the Serenity BDD CLI, a Java program that ships with the @serenity-js/serenity-bdd module.

Example Serenity BDD report

To generate Serenity BDD reports, configure your crew and scripts as follows:

wdio.conf.ts
serenity: {
    crew: [
        '@serenity-js/console-reporter',
        ['@serenity-js/serenity-bdd', { specDirectory: './test/specs' }],
        ['@serenity-js/core:ArtifactArchiver', { outputDirectory: './target/site/serenity' }],
    ],
},
package.json
{
  "scripts": {
    "clean": "rimraf target",
    "serenity": "failsafe clean wdio serenity:report",
    "wdio": "wdio run ./wdio.conf.ts",
    "serenity:report": "serenity-bdd run --source ./target/site/serenity --destination ./target/site/serenity"
  }
}

This requires additional dependencies:

npm install --save-dev @serenity-js/serenity-bdd npm-failsafe rimraf

→ Learn more: Serenity BDD Reporter guide | Migrating to the HTML Reporter

Upgrading to WebdriverIO 9​

WebdriverIO 9 deprecated or removed several configuration options common in WebdriverIO 8 projects.

To upgrade your WebdriverIO 8-based Serenity/JS project:

  • update the @serenity-js/*, webdriverio and any @wdio/* modules to the latest version,
  • update your tsconfig.json to target es2022,
  • replace the deprecated configuration properties with the new ones,
  • install the updated modules.

Updating dependencies​

To update your dependencies, use a tool like npm-check-updates. The command below will modify your package.json to update all @serenity-js/*, webdriverio, and @wdio/* modules to the latest version. The command won't install the modules themselves (we'll do this last):

npx -y npm-check-updates '/@serenity-js|webdriverio|@wdio/' -u

Please also note that WebdriverIO 9 no longer provides the devtools and @wdio/devtools-service modules as they're no longer required. If you had them in your package.json, you should remove them.

Updating TypeScript configuration​

Update compilerOptions configuration in your tsconfig.json to target at least es2022:

tsconfig.json
{
  "compilerOptions": {
-   "target": "es2021",
-   "lib": ["es2021", "dom"],
+   "target": "es2022",
+   "lib": ["es2022", "dom"],
    "module": "CommonJS",
    "moduleResolution": "node",
    "types": [
      "node",
      "@wdio/globals/types"
    ],
  }
}

Updating WebdriverIO configuration​

Modify your wdio.conf.ts to:

wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIOConfig {

-  automationProtocol: 'devtools',

-  autoCompileOpts: { ... }
+  tsConfigPath: './tsconfig.json',
}

If you'd like to use one of the new WebdriverIO 9 configuration types, combine it with the WithSerenityConfig interface:

wdio.conf.ts
import { WithSerenityConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIO.Config & WithSerenityConfig = {
    // ...
}

Installing updated modules​

Finally, install the updated modules:

npm install

Integration architecture​

To recap, Serenity/JS integrates with WebdriverIO through the @serenity-js/webdriverio module, which acts as a test runner adapter and:

This modular architecture enables Serenity/JS to enhance both classic WebdriverIO scenarios and those following the Screenplay Pattern with advanced reporting capabilities.

To enable this integration, you need to:

  1. Configure Serenity/JS test runner adapter and reporting services in your wdio.conf.ts file
  2. Optionally, use the Serenity/JS Screenplay Pattern APIs in your test scenarios
Serenity/JS + WebdriverIO integration architecture

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!

Don't forget to ⭐️ 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