@serenity-js/protractor

Serenity/JS Protractor

@serenity-js/protractor brings full Serenity reporting capabilities to Protractor framework and enables writing tests using the Screenplay Pattern.

Learn more about integrating Serenity/JS with Protractor.

Features

• Integrates Serenity/JS with Protractor providing standardised Screenplay Web API
• Supports Angular and non-Angular apps
• Enables Screenplay Pattern APIs in Protractor tests
• Supports all Serenity/JS reporting features
• TypeScript-first design with strong typing for safer and more predictable test code.

Installation

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

See the Serenity/JS Installation Guide.

Quick Start

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 Mocha.

Configuration

// 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/html-reporter', { outputDirectory: './reports/serenity-js' } ],
            [ '@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'

// 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').attemptsTo(
            Navigate.to('https://serenity-js.org'),
            Ensure.that(
                Text.of(SerenityJSWebsite.header()), 
                equals('Enable collaborative test automation at any scale!')
            ),
        )
    })
})

Documentation

• API Reference
• Screenplay Pattern Guide
• Serenity/JS Project Templates
• More examples and reference implementations
• Tutorial: First Web Scenario
• Tutorial: First API Scenario

Contributing

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community

• Community Chat
• Discussions Forum
  • Visit the 💡How to... ? section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

License

The Serenity/JS code base is licensed under the Apache-2.0 license, while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.