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.

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.

Features

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

Quick Start

$3

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

``sh
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.

$3

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

`ts
// 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

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

`json title="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:
- installation instructions in @serenity-js/serenity-bdd documentation,
- configuration examples in SerenityBDDReporter API docs,
- Serenity/JS examples on GitHub.

$3

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

`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 🚀')
),
)
})
})
`

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.

$3

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

`sh
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.

Documentation

- API Reference
- Screenplay Pattern Guide
- Serenity/JS Project Templates
- More examples and reference implementations
- Tutorial: First Web Scenario
- Tutorial: First API Scenario

Contributing

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community

- Community Chat
- Discussions Forum
- Visit the 💡How to... ? section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

License

The Serenity/JS code base is licensed under the Apache-2.0 license,
while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks
and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.