Integrating with Protractor
Protractor is both a test runner and a wrapper around the WebDriverJS testing library.
While optimised for testing Angular applications, Protractor is perfectly capable of interacting with websites and web applications built using any other framework or technology stack. Protractor runs tests in real browsers, uses native events, and browser-specific drivers to interact with your system as a user would.
This chapter covers:
- Integration architecture overview
- Integrating Protractor with Serenity/JS and Cucumber
- Integrating Protractor with Serenity/JS and Jasmine
- Integrating Protractor with Serenity/JS and Mocha
- Reporting
If you'd like to jump straight into the code, Serenity/JS GitHub repository provides a number of example implementations and project templates.
PRO TIP: The easiest way to get started with Serenity/JS and Protractor is to use one of the template projects available on GitHub. Serenity/JS template projects come with appropriate Serenity/JS modules and lower-level integration and test tools already configured.
Integration architecture overview
Protractor consists of two main components:
- the
protractor
command-line interface, which manages the web browser lifecycle, and a 3-rd party test runner you use to actually run your tests, - the
protractor
library, which provides WebDriverJS APIs your tests use to interact with your website or web application.
Protractor command-line interface doesn't run the tests by itself. Instead, it delegates this responsibility to Jasmine, or any other 3-rd party test runner, as long as you configure it with an appropriate adapter.
@serenity-js/protractor
module provides such an adapter, which on top of vastly improving built-in Protractor reporting capabilities, also enables you to run your test scenarios using Cucumber, Jasmine, or Mocha test runners.
Apart from providing a Protractor adapter, @serenity-js/protractor
module also gives you several dozen interfaces to help your web-based tests follow the Screenplay Pattern.
The architecture that you'll need to integrate Protractor with Serenity/JS looks as per the diagram below. We'll explore it in more detail in the context of specific test runners further on in this chapter.
Integrating Protractor with Serenity/JS and Cucumber
To integrate Serenity/JS with Protractor and Cucumber, @serenity-js/protractor/adapter
uses a test runner adapter and a Cucumber "formatter" available as part of the @serenity-js/cucumber
module.
This means that no matter whether your test suite uses Cucumber standalone, or Cucumber running behind Protractor, the lower-level integration with Serenity/JS works exactly the same and provides the same capabilities.
Installation
Assuming you already have a Protractor project set up, add the following dev dependencies:
To do that, run the following command in your terminal:
npm install --save-dev @serenity-js/{core,cucumber,protractor} @cucumber/cucumber
If you'd like to implement your test suite in TypeScript, also run:
npm install --save-dev typescript ts-node
Configuration
Modify your protractor.conf.js
file to register the @serenity-js/protractor/adapter
and configure it to execute your Cucumber scenarios ("specs
" in Protractor-speak) and require
your Cucumber step definitions:
// protractor.conf.js
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
runner: 'cucumber',
crew: [
// ... reporting services
]
},
specs: [ 'features/*.feature', ],
cucumberOpts: {
require: [
'features/step_definitions/**/*.ts', // or *.js
],
'require-module': ['ts-node/register'], // to add support for TypeScript
},
// ... other Protractor config omitted for brevity
};
To learn more about the available configuration options, check out:
SerenityConfig
, provided asserenity
inprotractor.conf.js
CucumberConfig
, provided ascucumberOpts
inprotractor.conf.js
ProtractorConfig
To install and configure Serenity/JS reporting modules appropriate for your project (a.k.a. the crew
) - follow the Serenity/JS reporting guide.
Using native Cucumber reporters
You can use native Cucumber reporters together with, or instead of those provided by Serenity/JS.
To do that, specify them using a <formatterName:outputFileName>
format to save their output to a file, or simply <formatterName>
to print their output to terminal. For example:
// protractor.conf.js
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
specs: [ 'features/*.feature', ],
cucumberOpts: {
format: [
'usage', // or 'usage:usage.txt' to print to file
'html:cucumber.html',
'snippets:snippets.txt',
'summary:summary.txt',
],
require: [
'features/step_definitions/**/*.ts', // or *.js
],
'require-module': ['ts-node/register'], // to add support for TypeScript
tags: ['~@wip'],
strict: false,
},
// ... other Protractor config omitted for brevity
};
PRO TIP: Cucumber.js supports only one native formatter per output. In particular, you can't have more than one Cucumber.js formatter writing to standard output or to the same file.
Please also note that when you configure Serenity/JS to use any of its reporting services (via the serenity.crew
option), the framework will automatically disable
any native Cucumber reporters printing to the terminal to avoid overlapping output.
You can, however, redirect output of such reporter to a file, so instead of usage
use usage:usage.txt
.
Integrating Protractor with Serenity/JS and Jasmine
To integrate Serenity/JS with Protractor and Jasmine, @serenity-js/protractor/adapter
uses a test runner adapter and a Jasmine reporter available as part of the @serenity-js/jasmine
module.
This means that no matter whether your test suite uses Jasmine standalone, or Jasmine running behind Protractor, the lower-level integration with Serenity/JS works exactly the same and provides the same capabilities.
Installation
Assuming you already have a Protractor project set up, add the following dev dependencies:
To do that, run the following command in your terminal:
npm install --save-dev @serenity-js/{core,jasmine,protractor} jasmine@3
If you'd like to implement your test suite in TypeScript, also run:
npm install --save-dev typescript ts-node
PRO TIP:
@serenity-js/jasmine
module enables your tests to use the latest version of Jasmine test runner, version 3. This version is newer than version 2 that ships with Protractor.
Configuration
Modify your protractor.conf.js
file to register the @serenity-js/protractor/adapter
and configure it to execute your Jasmine "specs
":
// protractor.conf.js
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
runner: 'jasmine',
crew: [
// ... reporting services
]
},
specs: [ 'spec/*.spec.ts', ], // or *.spec.js
jasmineNodeOpts: {
requires: [
'ts-node/register', // to add support for TypeScript
]
},
// ... other Protractor config omitted for brevity
};
To learn more about the available configuration options, check out:
SerenityConfig
, provided asserenity
inprotractor.conf.js
JasmineConfig
, provided asjasmineNodeOpts
inprotractor.conf.js
ProtractorConfig
To install and configure Serenity/JS reporting modules appropriate for your project (a.k.a. the crew
) - follow the Serenity/JS reporting guide.
Integrating Protractor with Serenity/JS and Mocha
To integrate Serenity/JS with Protractor and Jasmine, @serenity-js/protractor/adapter
uses a test runner adapter and a Mocha reporter available as part of the @serenity-js/mocha
module.
This means that no matter whether your test suite uses Mocha standalone, or Mocha running behind Protractor, the lower-level integration with Serenity/JS works exactly the same and provides the same capabilities.
Installation
Assuming you already have a Protractor project set up, add the following dev dependencies:
To do that, run the following command in your terminal:
npm install --save-dev @serenity-js/{core,mocha,protractor} mocha
If you'd like to implement your test suite in TypeScript, also run:
npm install --save-dev typescript ts-node
Configuration
Modify your protractor.conf.js
file to register the @serenity-js/protractor/adapter
and configure it to execute your Mocha "specs
":
// protractor.conf.js
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
runner: 'mocha',
crew: [
// ... reporting services
]
},
specs: [ 'spec/*.spec.ts', ], // or *.spec.js
mochaOpts: {
require: [
'ts-node/register', // to add support for TypeScript
],
},
// ... other Protractor config omitted for brevity
};
To learn more about the available configuration options, check out:
SerenityConfig
, provided asserenity
inprotractor.conf.js
MochaConfig
, provided asmochaOpts
inprotractor.conf.js
ProtractorConfig
To install and configure Serenity/JS reporting modules appropriate for your project (a.k.a. the crew
) - follow the Serenity/JS reporting guide.
Reporting
To install and configure Serenity/JS reporting modules appropriate for your project - follow the Serenity/JS reporting guide.
Love Serenity/JS? Spread the word on Twitter and LinkedIn!
Found a typo? You can fix it yourself or raise a ticket on GitHub.
If you'd like to help us bring more great tools and content to the Open-Source Community, become a GitHub Sponsor of Serenity/JS for as little as the cost of a cup of coffee.