@serenity-js/protractor

Serenity/JS

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

• Serenity/JS web testing tutorial
• Serenity/JS Handbook and Getting Started guides
• API documentation
• Serenity/JS Project Templates

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

Serenity/JS Protractor

@serenity-js/protractor module is a Screenplay Pattern-style adapter for Protractor framework, that helps with testing Angular, React, Vue and other frontend web apps.

Learn more about integrating Serenity/JS with Protractor.

Installation

To install this module, run:

npm install --save-dev @serenity-js/core @serenity-js/protractor

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide for Protractor.

Usage with Cucumber.js

To use Serenity/JS Protractor with Cucumber.js, install the following adapter:

npm install --save-dev @serenity-js/cucumber

Please note that Serenity/JS Protractor / Cucumber integration supports both Serenity/JS reporting services and native Cucumber.js reporters, so you can use this module as a drop-in replacement of protractor-cucumber-framework.

Learn more about integrating Serenity/JS Protractor with Cucumber.

Usage with Jasmine

To use Serenity/JS Protractor with Jasmine, install the following adapter:

npm install --save-dev @serenity-js/jasmine

Learn more about integrating Serenity/JS Protractor with Cucumber.

Usage with Mocha

To use Serenity/JS Protractor with Mocha, install the following adapter:

npm install --save-dev @serenity-js/mocha

Learn more about integrating Serenity/JS Protractor with Cucumber.

Configuring Protractor

// protractor.conf.js
exports.config = {
    // Tell Protractor to use the Serenity/JS framework Protractor Adapter
    framework:      'custom',
    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),
  
    // Configure Serenity/JS to use an appropriate test runner
    // and the Stage Crew Members we've imported at the top of this file
    serenity: {
        runner: 'jasmine',
        // runner: 'cucumber',
        // runner: 'mocha',
        crew: [
            '@serenity-js/console-reporter',
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: './target/site/serenity' } ],
            [ '@serenity-js/web:Photographer', {
                strategy: 'TakePhotosOfFailures', // or: 'TakePhotosOfInteractions'
            } ],
        ]
    },

    // configure Cucumber runner
    cucumberOpts: {
        // see the Cucumber configuration options below
    },

    // or configure Jasmine runner
    jasmineNodeOpts: {
        // see the Jasmine configuration options below
    },

    // or configure Mocha runner
    mochaOpts: {
        // see the Mocha configuration options below
    },

    // ... other Protractor-specific configuration   
}

Learn more about:

• Cucumber configuration options
• Jasmine configuration options
• Mocha configuration options
• Protractor configuration file.

Interacting with websites and web apps

import { actorCalled } from '@serenity-js/core'
import { Ensure, equals } from '@serenity-js/assertions'
import { By, Navigate, Target, Text } from '@serenity-js/web'
import { BrowseTheWebWithProtractor } from '@serenity-js/protractor'
import { protractor } from 'protractor'

// example Lean Page Object describing a widget we interact with in the test
class SerenityJSWebsite {
    static header = () =>
        PageElement.located(By.css('h1'))   // selector to identify the interactable element
            .describedAs('header')          // description to be used in reports
}

// example Jasmine test
describe('Serenity/JS', () => {
    
    it('works with Protractor and Jasmine', async () => {
        await actorCalled('Priya')
            .whoCan(
                BrowseTheWebWithProtractor.using(protractor.browser)
            )
            .attemptsTo(
                Navigate.to('https://serenity-js.org'),
                Ensure.that(
                    Text.of(SerenityJSWebsite.header()), 
                    equals('Next generation acceptance testing')
                ),
            )
    })
})

Template Repositories

The easiest way for you to start writing web-based acceptance tests using Serenity/JS, Protractor and either Mocha, Cucumber or Jasmine is by using one of the below template repositories:

• Serenity/JS, Mocha, and Protractor template
• Serenity/JS, Cucumber, and Protractor template
• Serenity/JS, Jasmine, and Protractor template

📣 Stay up to date

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!

Changelog

3.31.8 (2025-02-04)

Bug Fixes

• deps: update dependency semver to v7.7.1 (640931b)
• deps: update playwright dependencies to v1.50.1 (66f4946)
• deps: update webdriverio dependencies to ^9.7.2 (26b0d4b)