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.

Serenity/JS enhances WebdriverIO test suites by offering:

  • Enhanced Reporting - Gain detailed execution insights with visually rich reports and living documentation.
  • Reusable Code: Leverage the Screenplay Pattern for portable, maintainable tests that streamline collaboration.
  • Integration Libraries - Test APIs, manage local Node.js servers, and verify complex workflows effortlessly with ready-to-use libraries.

Serenity BDD Report Example

In this guide, you will learn:

Setting up a Serenity/JS project​

The easiest way to create a new Serenity/JS and WebdriverIO project is to use the WebdriverIO CLI wizard or clone one of the Serenity/JS + WebdriverIO project templates for your preferred test runner.

You can also add Serenity/JS to an existing WebdriverIO project by installing the required Serenity/JS modules and configuring the WebdriverIO test runner to use Serenity/JS framework and reporting services.

In this section, I'll walk you through each of these options.

Using the WebdriverIO CLI wizard​

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

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 integrate Serenity/JS with WebdriverIO, you'll need the following Serenity/JS modules:

To install the above modules, run the following command in your terminal:

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

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

Configuring Serenity/JS​

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.

Note that both the WebdriverIO CLI wizard and Serenity/JS Project Templates come pre-configured with Serenity/JS and WebdriverIO integration, so unless you want to customise the defaults, you won't need to change anything.

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

export const config: WebdriverIOConfig = {
    // Serenity/JS configuration
    framework: '@serenity-js/webdriverio',
    serenity: {
        runner: 'mocha', // or 'jasmine' or 'cucumber'
        crew: [
            '@serenity-js/console-reporter',
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
        ],
    },
}

If you'd like to use one of the new WebdriverIO 9 configuration types, combine it 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
}

Configuring Cucumber​

Supported Cucumber configuration options can be set using the serenity.cucumberOpts property in the wdio.conf.ts file.

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

export const config: WebdriverIOConfig = {
    // ... Serenity/JS configuration

    // Cucumber configuration
    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,
    },
}

For more information on configuring Cucumber, consult the Cucumber.js documentation and review the Serenity/JS, Cucumber, and WebdriverIO project template.

Configuring Jasmine​

Supported Jasmine configuration options can be set using the serenity.jasmineOpts property in the wdio.conf.ts file.

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

export const config: WebdriverIOConfig = {
    // ... Serenity/JS configuration

    // Jasmine configuration
    specs: [
        './test/specs/**/*.spec.ts'
    ],

    jasmineOpts: {
        defaultTimeoutInterval: 60000,
        specDir: 'test/specs',
    },
}

For more information on configuring Jasmine, consult the Jasmine documentation and review the Serenity/JS, Jasmine, and WebdriverIO project template.

Configuring Mocha​

Supported Mocha configuration options can be set using the serenity.mochaOpts property in the wdio.conf.ts file.

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

export const config: WebdriverIOConfig = {
    // ... Serenity/JS configuration

    // Mocha configuration
    specs: [
        './test/specs/**/*.spec.ts'
    ],

    mochaOpts: {
        ui: 'bdd',
        timeout: 60000,
        reporterOptions: {
            specDirectory: 'test/specs'
        },
    },
}

For more information on configuring Mocha, consult Mocha configuration examples on GitHub and review the Serenity/JS, Mocha, and WebdriverIO project template.

Configuring WebdriverIO​

Other WebdriverIO-specific configuration options, such as reporters, can be set in the wdio.conf.ts file as per the WebdriverIO configuration documentation.

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

export const config: WebdriverIOConfig = {
    // ... Serenity/JS configuration

    // ... Test runner configuration

    // WebdriverIO configuration
    reporters: [
        'spec',
    ],
}

Writing test scenarios​

Serenity/JS enables you to leverage the Screenplay Pattern to write expressive, maintainable test scenarios that align with your unique domain.

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 can use the WebdriverIO-managed browser, store and retrieve notes, and make HTTP requests.

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

To refer to an actor in your test scenarios, use 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:

Customising Serenity/JS 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/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
        ],
    },
}

Running tests and generating reports​

Projects created using the WebdriverIO CLI wizard or Serenity/JS Project Templates come pre-configured with the necessary NPM scripts to run your tests and generate Serenity/JS reports.

To run your tests and generate Serenity/JS reports, execute the following command in your terminal:

npm run serenity

Your test results will be available in the target/site/serenity directory. To view them, open the index.html file in your preferred web browser.

Using NPM scripts​

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

To produce Serenity BDD reports, your test suite must:

The pattern used by all the Serenity/JS Project Templates relies on using NPM scripts and the following Node modules:

  • 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
package.json
{
  "scripts": {
    "serenity": "failsafe serenity:clean wdio serenity:report",
    "serenity:clean": "rimraf target",
    "wdio": "wdio wdio.conf.ts",
    "serenity:report": "serenity-bdd run"
  }
}

To learn more about the SerenityBDDReporter, please consult:

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 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

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