@serenity-js/webdriverio

Serenity/JS

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!

• Serenity/JS Handbook and tutorial,
• API documentation,
• Serenity/JS project templates on GitHub.

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

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.

Installation

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/console-reporter',
            '@serenity-js/serenity-bdd',
            [ '@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
        './features/**/*.feature',
        // or Mocha/Jasmine spec files 
        // './spec/**/*.spec.ts',
    ],
    
    // add any additional native WebdriverIO reports
    // reporters: [
    //     'spec',
    // ],

    // ... other WebdriverIO-specific configuration   
};

Learn more about:

• Cucumber configuration options
• Jasmine configuration options
• Mocha configuration options
• WebdriverIO configuration file

Using custom Serenity/JS Actors

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

• BrowseTheWebWithWebdriverIO
• TakeNotes.usingAnEmptyNotepad()

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(
                    CallAnApi.at(this.apiUrl)
                );
                
            default:
                return actor.whoCan(
                    BrowseTheWebWithWebdriverIO.using(browser), // global WDIO browser
                    TakeNotes.usingAnEmptyNotepad(),
                );
        }

    }
}

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')
            .attemptsTo(
                Navigate.to('https://serenity-js.org'),
                Ensure.that(
                    Text.of(SerenityJSWebsite.header()),
                    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:

• Serenity/JS, Mocha, and WebdriverIO template
• Serenity/JS, Cucumber, and WebdriverIO template
• Serenity/JS, Jasmine, and WebdriverIO template (coming soon!)

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

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

Changelog

3.6.0 (2023-07-11)

Bug Fixes

• deps: update dependency https-proxy-agent to ^7.0.1 (f49b293)
• deps: update dependency https-proxy-agent to ^7.0.1 (9ea4610)
• deps: update dependency tiny-types to ^1.20.0 (6d7bf43)

Features

• playwright-test: enable BrowseTheWebWithPlaywright to reuse an existing page instance (5c2deb1), closes #1784
• playwright-test: introducing Component Testing with Serenity/JS and Playwright Test (7b3c6c8), closes #1784
• web: selectors are comparable and serialisable to JSON (b285389), closes #1784
• web: you can now use Serenity/JS Screenplay Pattern APIs for UI component testing (3c9aa4b), closes #1784