Skip to main content

external@serenity-js/webdriverio-8

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

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 WebdriverIO 8 module is intended for existing projects that can't yet upgrade to WebdriverIO 9. If you're starting a new project, we recommend using the Serenity/JS WebdriverIO module.

🚀 Why choose Serenity/JS?​

  • Write expressive, maintainable tests that align with your unique domain using the Serenity/JS Screenplay Pattern APIs.
  • Leverage advanced reporting to track progress, detect failures, and share results with both technical and business stakeholders.
  • Build on flexible, modular, and extensible architecture that supports a wide range of test automation needs.
  • Integrate with WebdriverIO 8 and modern test automation tools.

🛠️ Integrate WebdriverIO 8 with Serenity/JS in 4 steps​

1. Installing Serenity/JS modules​

To add Serenity/JS to an existing WebdriverIO 8 project, install the following Serenity/JS modules from NPM:

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

Learn more about Serenity/JS modules:

If you prefer to review a reference implementation first, clone a Serenity/JS Project Template for your preferred test runner.

2. Configuring Serenity/JS​

To enable integration with Serenity/JS, configure WebdriverIO as follows:

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

export const config: WebdriverIOConfig = {

    // Tell WebdriverIO to use Serenity/JS framework with the WebdriverIO 8 adapter
    // When you're ready to upgrade to WebdriverIO 9, switch to '@serenity-js/webdriverio'
    framework: '@serenity-js/webdriverio-8',

    // Serenity/JS configuration
    serenity: {
        // Configure Serenity/JS to use the appropriate adapter
        // for your test runner
        runner: 'cucumber', // or 'mocha', or 'jasmine'

        // Register Serenity/JS reporting services, a.k.a. the "stage crew"
        crew: [
            // Optional, print test execution results to standard output
            '@serenity-js/console-reporter',

            // Optional, produce Serenity BDD reports
            // and living documentation (HTML)
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', {
                outputDirectory: 'target/site/serenity'
            } ],

            // Optional, automatically capture screenshots
            // upon interaction failure
            [ '@serenity-js/web:Photographer', {
                strategy: 'TakePhotosOfFailures'
            } ],
        ]
    },

    // Location of your test files
    specs: [
        './test/specs/**/*.spec.ts',    // for Mocha or Jasmine
        // './features/**/*.feature',   // for Cucumber
    ],

    // Configure your Cucumber runner
    cucumberOpts: {
        // see Cucumber configuration options below
    },


    // ... or Jasmine runner
    jasmineOpts: {
        // see Jasmine configuration options below
    },

    // ... or Mocha runner
    mochaOpts: {
        // see Mocha configuration options below
    },

    runner: 'local',

    // Enable TypeScript in-memory compilation
    autoCompileOpts: {
        autoCompile: true,
        tsNodeOpts: {
            transpileOnly: true,
            project: 'tsconfig.json'
        }
    },

    // Any other WebdriverIO configuration
};

Learn more about:

3. Generating Serenity BDD reports and living documentation​

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

To learn more about the SerenityBDDReporter, please consult:

4. Writing a test scenario​

Assuming you're using WebdriverIO 8 with Mocha, create a test file under ./test/specs/example.spec.ts with the following contents:

// ./test/specs/example.spec.ts
import { describe, it } from 'mocha'

import { Ensure, equals } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { By, Navigate, PageElement, Text } from '@serenity-js/web'

describe('Example', () => {

    it('interacts with a web page', async () => {

        await actorCalled('Alice').attemptsTo(
            Navigate.to('https://serenity-js.org'),
            Ensure.that(
                Text.of(PageElement.located(By.id('cta-start-automating'))),
                equals('Start automating 🚀')
            ),
        )
    })    
})

You'll notice that the example test file uses:

You'll also notice that the file does not use the @serenity-js/webdriverio-8 module directly. This is because the @serenity-js/web module provides a higher-level API for interacting with web pages, allowing you to switch to @serenity-js/webdriverio whenever you're ready to upgrade to WebdriverIO 9 without changing your test scenarios.

You can learn more about these and other Serenity/JS modules in the Serenity/JS API documentation. You might also want to check out the Serenity/JS WebdriverIO integration guide for more details on configuring your framework.

4. Running your tests and generating reports​

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

npm test

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.

💡️ Learn Serenity/JS​

👋 Join the Serenity/JS Community​

📣 Stay up to date​

💛 Support Serenity/JS​

Support our mission to make test automation collaborative and easier to scale. Become a Serenity/JS GitHub Sponsor today!

GitHub Sponsors

Index

Abilities

Configuration

Models

Variables

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

Page Options