@serenity-js/webdriverio

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.

🚀 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 and modern test automation tools.

🛠️ Get started in 3 steps

Serenity/JS integrates with the WebdriverIO command line wizard to help you set up a new project with the required dependencies, configuration and example tests.

If you prefer to review a reference implementation first or use it as a starting point for your project, you can clone a Serenity/JS Project Template for your preferred test runner.

1. Using the WebdriverIO wizard

To use the WebdriverIO wizard to create a new project, run the following command in your computer terminal:

npm init wdio ./my-project

To create a Serenity/JS project, select the following options:

• Type of testing: E2E Testing
• Automation backend: any - Serenity/JS supports both local and remote WebdriverIO test runners; select local to keep it simple
• Environment: web
• Browser: any - Serenity/JS supports all browsers supported by WebdriverIO; selecting Chrome is a good starting point
• Framework: Jasmine with Serenity/JS, Mocha with Serenity/JS, or Cucumber with Serenity/JS; we'll use Mocha with Serenity/JS in this example
• Compiler: any - Serenity/JS supports both TypeScript and JavaScript; we recommend TypeScript for better tooling support
• Generate test files: yes, if you'd like Serenity/JS to give you a starting point for your test scenarios
• Test file location: accept the defaults unless you'd like to store your code in a different directory
• Test reporter: any, Serenity/JS configures the project to use Serenity/JS reporting services, and you can add native WebdriverIO reporters too if needed
• Plugins/add-ons/services: none; Serenity/JS doesn't require any additional plugins to work with WebdriverIO

To create a Serenity/JS, WebdriverIO and Cucumber project, follow the tutorial:

2. Writing a test scenario

Assuming you've chosen Mocha with Serenity/JS and requested the wizard to generate example test files for you, you'll find your first test file located at ./test/specs/example.spec.ts:

// ./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 🚀')
            ),
        )
    })
    
    // ... other examples
})

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 can learn more about these and other Serenity/JS modules in the Serenity/JS API documentation.

The configuration of your project is located in the wdio.conf.ts file. Check out the Serenity/JS WebdriverIO integration guide for more details.

3. Running your tests and generating reports

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

npm run serenity

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!

Changelog

3.32.2 (2025-06-21)

Bug Fixes

• deps: update webdriverio dependencies to ^9.15.0 (48c5ed5)
• serenity-bdd: correctly escape HTML entities in scenario parameter descriptions (708942e), closes #2879
• serenity-bdd: upgraded Serenity BDD CLI jar to 4.2.34 (fadf10a)
• webdriverio: support for WebdriverIO 9.15 (133d35e)