Protractor
Protractor is an end-to-end test framework for Angular and AngularJS applications, based on Selenium 3. Protractor runs tests against your application running in a real browser, interacting with it as a user would.
Protractor is now officially deprecated and has not received any updates since April 2020. You should not rely on Protractor for any new test automation projects, and instead use Serenity/JS with more modern and developer-friendly integration tools like WebdriverIO or Playwright Test.
Yes. The most common reason why you should introduce Serenity/JS to an existing Protractor project is that it can help you to reliably migrate your codebase to a more modern integration tool like WebdriverIO or Playwright in the next step.
Using Serenity/JS Screenplay Pattern APIs will also help you future-proof your codebase and make it agnostic of the underlying integration tools.
If you want to add Serenity/JS to an existing Protractor test suite, check out Extending Protractor with Serenity/JS.
In this article, you will learn:
- How to use Serenity/JS reporting services, including the Serenity BDD reporter, even if your test scenarios don't follow the Screenplay Pattern yet
- How to implement Protractor test scenarios using reusable Serenity/JS Screenplay Pattern APIs and the Serenity/JS Protractor module
- How Serenity/JS Web APIs will help you reliably migrate your tests from Protractor to WebdriverIO (the most compatible tool)
Examples and Project Templates​
If you'd like to dive straight into the code, Serenity/JS GitHub repository provides:
- Serenity/JS + Protractor project templates, which are the easiest way to start with the framework,
- several reference implementations, demonstrating using Serenity/JS with Protractor to write web-based acceptance tests
Using Serenity/JS reporting services​
@serenity-js/protractor
module provides a test runner adapter
you can attach to your Protractor test runner just like any other standard Protractor framework
.
Serenity/JS test runner adapters turn internal, test runner-specific events into Serenity/JS domain events that can contribute to test execution reports produced by Serenity/JS reporting services.
To use Serenity/JS reporting services in a Protractor project, you need to:
- attach the
@serenity-js/protractor
test runner adapter to the Protractor test runner - use
protractor.conf.js
to configure Serenity/JS to use the reporting services you want to use, such as theConsoleReporter
orSerenityBDDReporter
Installing Serenity/JS test runner adapter​
Assuming you already have a Protractor project, add Serenity/JS Protractor and web integration modules:
You might also want to install Serenity/JS reporting services:
To do the above, run the following command in your terminal:
- npm
- Yarn
npm install --save-dev @serenity-js/core @serenity-js/console-reporter @serenity-js/protractor @serenity-js/web @serenity-js/serenity-bdd
yarn add --dev @serenity-js/core @serenity-js/console-reporter @serenity-js/protractor @serenity-js/web @serenity-js/serenity-bdd
Protractor offers a test runner that uses Jasmine, Mocha, or Cucumber to run your test scenarios. Since the task of running the scenarios is delegated to another tool, you'll need to follow the installation instructions to add a Serenity/JS test runner adapter for the runner you've decided to use.
See Serenity/JS test runner adapter installation instructions for:
Configuring Serenity/JS​
To use Serenity/JS reporting services in a Protractor project,
modify your protractor.conf.js
configuration file
to register Serenity/JS Protractor adapter as a custom
Protractor framework
and list any Serenity/JS reporting services under crew
:
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
crew: [
'@serenity-js/console-reporter',
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
[ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ],
]
},
// other Protractor config
}
Learn more about configuring Serenity/JS Protractor adapter and Serenity/JS reporting services.
Configuring Protractor​
Protractor relies on Cucumber, Jasmine, or Mocha to execute your test scenarios. However, it is responsible for configuring the test runners themselves. To learn about the test runner configuration options, follow the Serenity/JS Protractor configuration guide.
To find out how to define test scenarios, check out the respective guide on using Serenity/JS with:
To learn about other Protractor configuration options, consult the Serenity/JS Protractor API docs.
Using Serenity/JS Screenplay Pattern APIs​
Serenity/JS actor model works great with Protractor and Serenity/JS Screenplay Pattern APIs can help your team implement Protractor test scenarios that are easy to read and understand.
The fastest way to get started with Serenity/JS and Protractor is to use one of the Serenity/JS + Protractor project templates. However, if you're adding Serenity/JS to an existing project or simply want to understand how the integration works, this guide is for you.
Referring to actors in test scenarios​
When you configure Serenity/JS Protractor
as the Protractor framework
,
Serenity/JS automatically creates and makes available a default cast of actors
where every actor has the abilities to:
BrowseTheWebWithProtractor
using the globalbrowser
TakeNotes.usingAnEmptyNotepad()
This means that any actors you refer to in your test scenarios using
actorCalled
and actorInTheSpotlight
functions are configured using
this default cast, and already have access to the Protractor-managed browser instance.
Since Protractor uses Jasmine, Mocha, or Cucumber to run your test scenarios, please refer to their dedicated guides to learn more about using Serenity/JS actors with:
Configuring a custom cast of actors​
You can replace the default cast of actors
by providing a custom implementation via serenity.actors
configuration option in your protractor.conf.js
.
For example, to implement a cast where every actor can BrowseTheWebWithProtractor
,
TakeNotes
and CallAnApi
, you could create a MyActors
class like this:
const { TakeNotes } = require('@serenity-js/core')
const { CallAnApi } = require('@serenity-js/rest')
const { BrowseTheWebWithProtractor } = require('@serenity-js/protractor')
exports.Actors = class Actors {
constructor(apiUrl) {
this.apiUrl = apiUrl
}
prepare(actor) {
return actor.whoCan(
BrowseTheWebWithProtractor.using(require('protractor').browser),
TakeNotes.usingAnEmptyNotepad(),
CallAnApi.at(this.apiUrl),
);
}
}
Protractor doesn't allow you to use the browser
global variable in protractor.conf.js
.
That's why you need to create a custom implementation of Cast
and only refer to browser
in Cast.prepare
method.
Protractor doesn't allow you to use TypeScript in protractor.conf.js
.
That's why MyActors
needs to be implemented in plain-old JavaScript.
Next, modify your Protractor configuration file to provide your custom MyActors
implementation:
const { MyActors } = require('./test/MyActors');
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
actors: new MyActors(),
crew: [
'@serenity-js/console-reporter',
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
[ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ],
]
},
// other Protractor config
}
Migrating from Protractor to WebdriverIO​
Follow the Serenity/JS Protractor migration guide