Skip to main content

WebdriverIO

WebdriverIO is a progressive automation framework built to automate modern web and mobile applications. WebdriverIO leverages the power of the WebDriver and WebDriver-BiDi protocols that are developed and supported by all browser vendors and guarantees a true cross-browser testing experience. Furthermore, WebdriverIO also supports alternative, proprietary automation protocols like Chrome DevTools via Puppeteer.

Extending existing WebdriverIO Test suites

If you want to add Serenity/JS to an existing WebdriverIO test suite, check out Extending WebdriverIO with Serenity/JS.

In this article, you will learn:

Creating a new project​

The easiest way to create a new Serenity/JS and WebdriverIO project is to use the WebdriverIO configuration wizard, or clone one of the Serenity/JS + WebdriverIO project templates.

Using the WebdriverIO wizard​

To use the WebdriverIO configuration wizard, run the following command in your computer terminal:

npm init wdio

Next, select the following options:

  • Type of testing: E2E Testing
  • Automation backend: any, as Serenity/JS supports both local and remote WebdriverIO test runners
  • Environment: web
  • Browser: any, as Serenity/JS supports all browsers supported by WebdriverIO
  • Framework: Jasmine with Serenity/JS, Mocha with Serenity/JS, or Cucumber with Serenity/JS
  • Compiler: any, as Serenity/JS supports both TypeScript and JavaScript (we recommend TypeScript)
  • 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

Check out the below video to see how to create a new project step by step:

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

Using Serenity/JS Project Templates​

If you'd like to dive straight into the code, Serenity/JS GitHub repository provides:

Using Serenity/JS reporting services​

@serenity-js/webdriverio module provides a test runner adapter you can attach to your WebdriverIO test runner just like any other standard WebdriverIO framework.

Serenity/JS test runner adapters

Serenity/JS test runner adapters turn internal, test runner-specific events into Serenity/JS domain events that can contribute to test execution reports produced by Serenity/JS reporting services.

To use Serenity/JS reporting services in a WebdriverIO Test project, you need to:

Serenity/JS + WebdriverIO integration architecture

Installing Serenity/JS test runner adapter​

Follow WebdriverIO installation instructions to create a new WebdriverIO project.

Use TypeScript to get the most out of your development tools

WebdriverIO installation wizard will ask you whether you want to use TypeScript or JavaScript to implement your test scenarios. Choosing TypeScript offers improved tooling support in IDEs such as JetBrains and Visual Studio Code.

Next, add Serenity/JS WebdriverIO and web integration modules:

You might also want to install Serenity/JS reporting services:

To do the above, run the following command in your terminal:

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

WebdriverIO offers a local runner that uses Jasmine, Mocha, or Cucumber to run your test scenarios. Since the task of running the scenarios is delegated to another tool, you'll need to follow the installation instructions to add a Serenity/JS test runner adapter for the runner you've decided to use.

See Serenity/JS test runner adapter installation instructions for:

Configuring Serenity/JS​

To use Serenity/JS reporting services in a WebdriverIO project, modify your wdio.conf.ts configuration file to register Serenity/JS WebdriverIO adapter as a WebdriverIO framework and list any Serenity/JS reporting services under crew:

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

export const config: WebdriverIOConfig = {
    framework: '@serenity-js/webdriverio',
    serenity: {
        crew: [
            '@serenity-js/console-reporter',
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
        ],
    },
}

Learn more about configuring Serenity/JS WebdriverIO adapter and Serenity/JS reporting services.

Configuring WebdriverIO​

WebdriverIO relies on Cucumber, Jasmine, or Mocha to execute your test scenarios. However, it is responsible for configuring the test runners themselves. To learn about the test runner configuration options, follow the Serenity/JS WebdriverIO configuration guide.

To find out how to define test scenarios, check out the respective guide on using Serenity/JS with:

To learn about other WebdriverIO configuration options, consult the WebdriverIO documentation.

Using Serenity/JS Screenplay Pattern APIs​

Serenity/JS actor model works great with WebdriverIO and Serenity/JS Screenplay Pattern APIs can help your team implement WebdriverIO test scenarios that are easy to read and understand.

The fastest way to get started with Serenity/JS and WebdriverIO is to use one of the Serenity/JS + WebdriverIO project templates. However, if you're adding Serenity/JS to an existing project or simply want to understand how the integration works, this guide is for you.

Referring to actors in test scenarios​

When you configure Serenity/JS WebdriverIO as the WebdriverIO framework, Serenity/JS automatically creates and makes available a default cast of actors where every actor has the abilities to:

This means that any actors you refer to in your test scenarios using actorCalled and actorInTheSpotlight functions are configured using this default cast, and already have access to the WebdriverIO-managed browser instance.

Since WebdriverIO uses Jasmine, Mocha, or Cucumber to run your test scenarios, please refer to their dedicated guides to learn more about using Serenity/JS actors with:

Configuring a custom cast of actors​

You can replace the default cast of actors by providing a custom implementation via serenity.actors configuration option in your wdio.conf.ts.

For example, to implement a cast where every actor can BrowseTheWebWithWebdriverIO, TakeNotes and CallAnApi, you could create a MyActors class like this:

test/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 {
    // use constructor parameters to pass properties from the configuration file
    constructor(private readonly apiUrl: string) {
    }

    prepare(actor: Actor): Actor {
        return actor.whoCan(
            BrowseTheWebWithWebdriverIO.using(browser), // use global browser object
            TakeNotes.usingAnEmptyNotepad(),
            CallAnApi.at(this.apiUrl),
        );
    }
}
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/MyActors'

export const config: WebdriverIOConfig = {
    framework: '@serenity-js/webdriverio',
    serenity: {
        actors: new MyActors('https://api.example.org'),
        crew: [
            '@serenity-js/console-reporter',
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
        ],
    },
}