Skip to main content

external@serenity-js/webdriverio

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.

Installation

To install this module, use an existing WebdriverIO project or generate a new one by running:

npm init wdio .

Install the below Serenity/JS modules in your WebdriverIO project directory:

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

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide fpr WebdriverIO.

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
// wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'

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

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

📣 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

Index

Variables

externaldefault

default: { init: any }

WebdriverIO Framework Adapter integrates WebdriverIO with Serenity/JS


Type declaration

  • init: function
    • init(cid: string, config: WebdriverIOConfig, specs: string[], capabilities: RemoteCapability, reporter: EventEmitter<DefaultEventMap> & ProvidesWriteStream & InitialisesReporters): Promise<{ hasTests: () => boolean; run: () => Promise<number> }>

    • Parameters

      • externalcid: string
      • externalconfig: WebdriverIOConfig
      • externalspecs: string[]
      • externalcapabilities: RemoteCapability
      • externalreporter: EventEmitter<DefaultEventMap> & ProvidesWriteStream & InitialisesReporters

      Returns Promise<{ hasTests: () => boolean; run: () => Promise<number> }>