Serenity/JS with WebdriverIO 8 🚀

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:

• @serenity-js/core
• @serenity-js/web
• @serenity-js/webdriverio-8
• @serenity-js/assertions
• @serenity-js/rest
• @serenity-js/console-reporter
• @serenity-js/serenity-bdd

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:

• Serenity/JS Cucumber configuration options
• Serenity/JS Jasmine configuration options
• Serenity/JS Mocha configuration options
• WebdriverIO configuration file

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:

• produce intermediate Serenity BDD .json reports, by registering SerenityBDDReporter as per the configuration instructions
• invoke the Serenity BDD CLI when you want to produce the report, by calling serenity-bdd run

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

{
  "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:

• installation instructions in @serenity-js/serenity-bdd documentation,
• configuration examples in SerenityBDDReporter API docs,
• Serenity/JS examples on GitHub.

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:

• @serenity-js/assertions - to make assertions about the state of the system under test
• @serenity-js/core - to create and manage actors
• @serenity-js/web - to interact with web pages

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

• Serenity/JS WebdriverIO integration guide - Integrate Serenity/JS with your WebdriverIO test suite, enable Serenity BDD reports, and start using the Screenplay Pattern
• Serenity/JS Handbook - Write high-quality automated acceptance tests with Serenity/JS
• Serenity/JS API documentation - Explore Serenity/JS modules and features
• Serenity/JS Project Templates - Kickstart your projects with best practices built right in

👋 Join the Serenity/JS Community

• Serenity/JS Community chat channel - Meet Serenity/JS developers and maintainers
• Serenity/JS Forum - Find answers to your Serenity/JS questions
• Contribute to Serenity/JS - Learn how to propose features, report bugs, and contribute to the Serenity/JS codebase

📣 Stay up to date

• Serenity/JS on YouTube - Subscribe for tutorials, demos, conference talks, and more
• Serenity/JS on LinkedIn - Follow for release and community event announcements
• Serenity/JS on GitHub - Star Serenity/JS to help others discover the framework!

💛 Support Serenity/JS

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