Skip to main content

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 deprecated

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.

Should I use Serenity/JS with my existing Protractor project?

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.

Extending existing Protractor test suites

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:

Examples and Project Templates

If you'd like to dive straight into the code, Serenity/JS GitHub repository provides:

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

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:

Serenity/JS + Protractor integration architecture

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 install --save-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:

protractor.conf.js
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:

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:

test/MyActors.js
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),
);
}
}
No browser in the configuration file

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.

No TypeScript in the configuration file

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:

protractor.conf.js
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

Introducing Serenity/JS Screenplay Pattern APIs in your test scenarios can help your code become and stay integration tool-agnostic. It can also help you migrate from Protractor to a more modern tool like WebdriverIO.

Your feedback matters!

Are you planning to migrate your tests from Protractor to another integration tool?

I'm considering writing a tutorial, recording a video, or maybe even a course on how to migrate your tests from Protractor to WebdriverIO or Playwright in a safe and reliable way that minimises the risk to your organisation.

If you're interested in that, let me know in the comments! 👇👇👇

Also make sure to follow Serenity/JS to get notified 🔔 when new content is available! 🎉

LinkedIn Follow YouTube Follow GitHub Sponsors