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:

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.

graph TB SUT(["far:fa-window-maximize Web App"]) DEV(["fas:fa-laptop-code Developer"]) PCLI["fas:fa-terminal protractor"] P(["protractor"]) PCF["fas:fa-file protractor.conf.js"] SPA(["@serenity-js/protractor/adapter"]) SP(["@serenity-js/protractor"]) SC(["@serenity-js/core"]) TR(["fas:fa-plug 3rd-party test runner"]) TRA(["fas:fa-plug Serenity/JS test runner adapter"]) SPECS["fas:fa-tasks specs"] R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> PCLI PCLI -- loads --> PCF PCLI -- uses --> SPA PCF -- configures --> SC SPA -- registers --> TRA SPA -- manages --> TR TR -- notifies --> TRA TR -- executes --> SPECS SPECS -- use --> SP SP -- notifies --> SC SP -- uses --> P P -- interacts with --> SUT TRA -- notifies --> SC SC -- notifies --> R class TR socket class TRA socket class SPECS socket class R socket click SP "/modules/protractor" click SC "/modules/core" click R "/handbook/reporting/index.html"

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.

graph TB SUT(["far:fa-window-maximize Web App"]) DEV(["fas:fa-laptop-code Developer"]) PCLI["fas:fa-terminal protractor"] P(["protractor"]) PCF["fas:fa-file protractor.conf.js"] SPA(["@serenity-js/protractor/adapter"]) SP(["@serenity-js/protractor"]) SC(["@serenity-js/core"]) TR(["@cucumber/cucumber"]) TRA(["@serenity-js/cucumber"]) SPECS["fas:fa-tasks *.feature"] STEPS["fas:fa-file step_definitions/*.ts"] R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> PCLI PCLI -- loads --> PCF PCLI -- uses --> SPA PCF -- configures --> SC SPA -- registers --> TRA SPA -- manages --> TR TR -- notifies --> TRA TR -- parses --> SPECS TR -- uses --> STEPS STEPS -- use --> SP SP -- notifies --> SC SP -- uses --> P P -- interacts with --> SUT TRA -- notifies --> SC SC -- notifies --> R class R socket click SP "/modules/protractor" click SC "/modules/core" click R "/handbook/reporting/index.html"

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:

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.

graph TB SUT(["far:fa-window-maximize Web App"]) DEV(["fas:fa-laptop-code Developer"]) PCLI["fas:fa-terminal protractor"] P(["protractor"]) PCF["fas:fa-file protractor.conf.js"] SPA(["@serenity-js/protractor/adapter"]) SP(["@serenity-js/protractor"]) SC(["@serenity-js/core"]) TR(["jasmine"]) TRA(["@serenity-js/jasmine"]) SPECS["fas:fa-tasks *.spec.ts"] SPECS -- use --> SP R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> PCLI PCLI -- loads --> PCF PCLI -- uses --> SPA PCF -- configures --> SC SPA -- registers --> TRA SPA -- manages --> TR TR -- notifies --> TRA TR -- runs --> SPECS SP -- notifies --> SC SP -- uses --> P P -- interacts with --> SUT TRA -- notifies --> SC SC -- notifies --> R class R socket click SP "/modules/protractor" click SC "/modules/core" click R "/handbook/reporting/index.html"

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:

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.

graph TB SUT(["far:fa-window-maximize Web App"]) DEV(["fas:fa-laptop-code Developer"]) PCLI["fas:fa-terminal protractor"] P(["protractor"]) PCF["fas:fa-file protractor.conf.js"] SPA(["@serenity-js/protractor/adapter"]) SP(["@serenity-js/protractor"]) SC(["@serenity-js/core"]) TR(["mocha"]) TRA(["@serenity-js/mocha"]) SPECS["fas:fa-tasks *.spec.ts"] SPECS -- use --> SP R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> PCLI PCLI -- loads --> PCF PCLI -- uses --> SPA PCF -- configures --> SC SPA -- registers --> TRA SPA -- manages --> TR TR -- notifies --> TRA TR -- runs --> SPECS SP -- notifies --> SC SP -- uses --> P P -- interacts with --> SUT TRA -- notifies --> SC SC -- notifies --> R class R socket click SP "/modules/protractor" click SC "/modules/core" click R "/handbook/reporting/index.html"

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:

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.

Sponsor