TypeScript icon, indicating that this package has built-in type declarations

3.2.1 • Public • Published


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

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

⭐️ Get started with Serenity/JS!

👋 Join the Serenity/JS Community!

Serenity/JS WebdriverIO

@serenity-js/webdriverio module is a Screenplay Pattern-style adapter for WebdriverIO that will help you with testing Web and mobile apps.


To install this module, run the following command in your WebdriverIO project directory:

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

Next, install a Serenity/JS test runner adapter appropriate for your preferred test runner.

Usage with Cucumber.js

To use Serenity/JS WebdriverIO with Cucumber.js, install the following adapter:

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.

Usage with Jasmine

To use Serenity/JS WebdriverIO with Jasmine, install the following adapter:

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

Usage with Mocha

To use Serenity/JS WebdriverIO with Mocha, install the following adapter:

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

Configuring WebdriverIO

To integrate Serenity/JS with WebdriverIO, configure your wdio.conf.ts to specify framework: '@serenity-js/webdriverio'. You can configure Serenity/JS in the same file.

// wdio.conf.ts

// Optional, import custom Actors if needed; More on this below.
import { Actors } from './serenity/Actors.ts'

export const config: WebdriverIOConfig = {
    // Tell WebdriverIO to use Serenity/JS framework
    framework: '@serenity-js/webdriverio',

    // Serenity/JS configuration
    serenity: {
        // Configure Serenity/JS to use an appropriate test runner adapter
        runner: 'cucumber',
        // runner: 'mocha',
        // runner: 'jasmine',

        // Optional, register custom Cast to configure your Serenity/JS actors
        actors: new Actors(`https://api.example.org`),
        // Register Serenity/JS reporting services, a.k.a. the "stage crew"
        crew: [
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
            [ '@serenity-js/web:Photographer', { 
                strategy: 'TakePhotosOfFailures', // or: 'TakePhotosOfInteractions'
            } ],

    // configure Cucumber runner
    cucumberOpts: {
        // see the Cucumber configuration options below

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

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

    specs: [
        // load Cucumber feature files
        // or Mocha/Jasmine spec files 
        // './spec/**/*.spec.ts',
    // add any additional native WebdriverIO reports
    // reporters: [
    //     'spec',
    // ],

    // ... other WebdriverIO-specific configuration   

Learn more about:

Using custom Serenity/JS Actors

By default, Serenity/JS uses a default cast of actors where every actor can:

If you're planning to implement scenarios where actors have additional abilities, you can replace this default setup with a custom Cast, like this one:

// serenity/Actors.ts
import { Actor, Cast, TakeNotes } from '@serenity-js/core';
import { CallAnApi } from '@serenity-js/rest';
import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
import type { Browser } from 'webdriverio';

export class Actors implements Cast {

    // Inject custom parameters via constructor
    constructor(private readonly apiUrl: string) {
    prepare(actor: Actor): Actor {
        // You can assign abilities based on actor name, env variables, and so on
        switch (actor.name) {
            case 'Apisitt':
                return actor.whoCan(
                return actor.whoCan(
                    BrowseTheWebWithWebdriverIO.using(browser), // global WDIO browser


Using Serenity/JS with WebdriverIO and Mocha

// specs/example.spec.ts
import { actorCalled } from '@serenity-js/core';
import { Ensure, equals } from '@serenity-js/assertions';
import { By, Navigate, PageElement, Text } from '@serenity-js/web';
import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';

// example Lean Page Object describing a widget we interact with in the test
class SerenityJSWebsite {
    static header = () =>
        PageElement.located(By.css('h1'))   // selector to identify the interactable element
            .describedAs('header');         // description to be used in reports

describe('Serenity/JS', () => {
    it('works with WebdriverIO and Mocha', async () => {
        // actorCalled(name) instantiates or retrieves an existing actor identified by name
        // Actors class configures the actors to use WebdriverIO 
        await actorCalled('Wendy')
                    equals('Enable collaborative test automation at any scale!')

To learn more, check out the example projects.

Template Repositories

The easiest way for you to start writing web-based acceptance tests using Serenity/JS, WebdriverIO and either Mocha, Cucumber or Jasmine is by using one of the below template repositories:

📣 Stay up to date

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

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!

GitHub Sponsors


npm i @serenity-js/webdriverio

DownloadsWeekly Downloads






Unpacked Size

482 kB

Total Files


Last publish


  • jan-molak